Create documentation for requesting design review

[maylee]

From: ​https://tahoe-lafs.org/trac/tahoe-lafs/wiki/Patches

Original text:

To request a design review, just explain your design (with or without a patch) and ask for feedback. Completion of a design review will normally not directly result in a patch being committed. The main goal of a design review is to give the person working on the ticket confidence that there are no show-stopping issues with the approach they are taking, and to get feedback on smaller issues that are useful to take into account before doing further work on a patch.

Example replacement text:

If you have a design that you would like feedback on, open a PR and explain your design, attaching files as needed. Request a review from Tahoe Committers. The goal of a design review is to ensure there are no show-stopping issues before beginning work and to address things that should be taken into account (e.g., how to break the work up into multiple tickets or PRs).

[exarkun]

I suggest any such documentation should come with a definition of "design".

[maylee]

Would linking to the following be suitable, or should we have something more specific to the organization? Perhaps a caveat that the more [insert any range of suitable qualifiers here] their design is, the more easy it will be respond to?

​https://en.wikipedia.org/wiki/Software_design

I have also wondered if there should be a direct suggestion of preferred file formats or tools.

[exarkun]

Would linking to the following be suitable, or should we have something more specific to the organization?

I don't think the Wikipedia page helps much. Sorry I wasn't more clear with my comment, I probably should have just saved it for a more reasonable hour.

Here's what I really meant. If the developer guide says you can have a "design review" it should explain what that actually means. What is a "design" and what constitutes a review of it? The vague Wikipedia page doesn't answer either of these questions. It talks about the vague notion of what design in software is but you can't read that page and then create a software design. *My* suspicion is that this idea is just too abstract to actually be useful. Instead, it's just an extra barrier to contribution (either the barrier of more docs to read and remember before you can contribute or a barrier in actually trying to produce such a design).

I'm 100% supportive of doing specifications where they are helpful (eg, to have a normative definition of behavior that is not just a reference implementation). A "specification" has at least one critical, concrete attribute which we can point at and use for evaluation: either it tells you everything necessary to create an implementation or it does not.

My first comment about having a definition of "design" was aimed at this. What is at least one concrete attribute about "a design" design and say "yes this document has it" or "no this document does not have it"? A list of such attributes would be the "definition" I was asking for.

[maylee]

Thanks for the feedback and input. I'd like to draft a list of attributes (and I have some notes and yet more links to that effect), but first I'd like to ask if you think instructions for "requesting a design review" (technical spec? technical design?) is a useful contributor document to have? Or if there's a type of documentation to the same end that would be more useful? Or if such documentation should be omitted entirely at this point?

[exarkun]

*I'm* not convinced any such document is necessary or useful at this point. Instead, I think if someone wants to undertake a major development effort, they should start a conversation with the currently active developers about it.

[maylee]

*I'm* not convinced any such document is necessary or useful at this point.

Okay, unless I hear something pressing to the contrary I think the production of this particular document can rest for the time being :)