doc/design: update review process guidelines regarding tooling

[jiceatscion]

The guidelines for the design review process are fairly precise in the abstract but lack specificity when it comes to the mechanisms to use. One specific issue is that after a proposal is approved and a design doc is submitted, it does not specify how the design document is discussed and finalized. Does the PR for the new design doc remain open (and therefore the design doc unmerged)? That is the implicit consequence of the current wording and seems inconvenient since the only version of the doc is in the PR and in the owner's private branch. It might work well if the design is almost finalized at the time the proposal is approved, but then that implies that all the refinement occurred upstream, during the proposal discussion when the only copy of the proposed design doc is embedded in the proposal issue itself, which is even less convenient.

I suggest amending the process as follows:

• At the end of the proposal review, the design's objectives and general approach are agreed upon, but there might not be an almost finished design doc.
• Following the proposal's approval, a first version of the design doc is submitted as a PR and can be merged if the reviewers think it is going in the right direction. The document is in the state WIP, which is indicated in the document's header. The document is linked to the WIP section of the design docs index.
• Following the merging of the initial revision of the design doc, the proposal issue may be closed or not; I am undecided about that - opinions especially welcome. The next step depends on that:
  • If we keep the original issue: it becomes the vehicle for discussions and subsequent updates to the design, through multiple PRs.
  • If we close the original issue: we open a new one, titled something like "doc/design: finalize xyz", and it becomes the vehicle for discussions and subsequent PRs.
• Once the design doc seems done, we have a call for objections and in the absence of such, we move the document from WIP to final (and into the Active section of the index) and that last PR closes the issue.

If that sounds good I will propose an edit to the guidelines.

Please let me know what you think and which if the two options, if any, you favor.

[tzaeschke]

I think I would be in favor of closing the original issue. If i understand correctly, it would be kept open only for further discussion.

My thinking is that further discussions are not guaranteed, the design may be good as it is. Also, with two issues open, we risk having the discussion in two places in parallel, especially considering external contributors that may not be familiar with the process. Does that make sense?

[jiceatscion]

I think I would be in favor of closing the original issue. If i understand correctly, it would be kept open only for further discussion.

Yes.

My thinking is that further discussions are not guaranteed, the design may be good as it is. Also, with two issues open, we risk having the discussion in two places in parallel, especially considering external contributors that may not be familiar with the process. Does that make sense?

Well, the two alternatives that I was considering were to either keep using the original issue until the design is approved in its final state, or to close it and open a new one for tracking the design changes. I wasn't considering having two issues open. However, I do lean, like you towards opening a new issue, since the purpose changes from proposal approval to design writing.

I'll start writing it up that way; betting on no objection.