DOC: Add a "User messaging" design doc

[jsheunis]

This PR:

• Aims to address Design / developer docs for how&when to implement exception raises/ logging / results yielding / hints #6613
• Adds a design specification "User messaging: result records vs exceptions vs logging"
• This specification aims to delineate the applicable contexts for using result records, exceptions, logging, or other types of user messaging methods.

TODOs:

• @datalad/developers: all please review the suggested design, since it will set the specification for future changes to the code base (+ extensions), as well as refactoring efforts
• Examples to be added to help developers apply the design specifications to their own extension code or to core contributions
• A description of the UI module and its use to be added
• Add changelog entry

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: +0.15 🎉

Comparison is base (4c9d834) 90.61% compared to head (4736a88) 90.76%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #7310      +/-   ##
==========================================
+ Coverage   90.61%   90.76%   +0.15%     
==========================================
  Files         324      325       +1     
  Lines       43034    43244     +210     
  Branches        0     5766    +5766     
==========================================
+ Hits        38994    39252     +258     
+ Misses       4040     3976      -64     
- Partials        0       16      +16     

see 120 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[adswa]

Thanks a lot for writing this up, this summarizes a lot of principles and guidelines really well. I left a few comments. Overall, I would agree with almost everything you outlined here, and I'm also curious what @yarikoptic and @mih say.

[mih]

Thanks for writing this up. I think it will need a few iteration to bring us all on the same page. I have left a bunch of comments.

In general, I'd prefer if we try to find the strongest language that we can. I fear that with shoulds and mays, we and up with something that is hard to use as an actionable specification.

[mih]

IMHO This is not an optimal statement, but I cannot come up with a better one, quickly.

[yarikoptic]

If this statement is concerning only Interfaces implementations, then I would agree. But then there is no clarity on either it concerns those or any part of the code, e.g. a function, which might be just compute_y(x) and which

• if just a regular classical Python function -- would raise ValueError or TypeError exception
• if somehow is "an interface" -- yield "impossible" record.

how does developer to decide between the two?

Overall -- is this document specifically just about subclasses of Interfaces or only the first section on return records is?

[jsheunis]

Overall -- is this document specifically just about subclasses of Interfaces or only the first section on return records is?

I think it's both. The main theme is user messaging, and the reality is that most of that happens in response to a call via the Interface class. But also: we aren't giving general advice i.e. it should not be seen as a comment on what to do with general/classic Python code.

[yarikoptic]

Some thoughts, haven't finished review though so may be some are premature

[jsheunis]

Note: the PR is still in draft because of the section Examples that hasn't been added. This would contain code examples of how to use each user messaging method. However: I would like to know opinions on whether this is actually necessary? I'm leaning towards it being a nice-to-have, but not strictly necessary.

[bpoldrack]

Thx for taking that on, @jsheunis!

[jsheunis]

@datalad/developers thanks for the comments so far. I must still add minor updates after the review of @bpoldrack. And then I would like input on whether we need examples or not? And lastly, a last sanity check on the latest state would probably be a good idea, for those who care strongly about the content here.

[jsheunis]

Comments by @yarikoptic in a dev call: examples could point to commit-tracked implementations in existing code.

[codeclimate]

Code Climate has analyzed commit fc28212 and detected 0 issues on this pull request.

View more on Code Climate.

[yarikoptic]

quickly spotted the NameError: name 'command' is not defined so left some suggestions ;-)

[jsheunis]

@yarikoptic thanks, I committed the suggestions

[yarikoptic]

Thank you @jsheunis for pushing it through!

[yarikoptic-gitmate]

PR released in 0.19.0