proposal: all: add explicit decision doc for large changes

[rsc]

#33670 talks about how to identify large changes. Having done that, we should expect a large discussion. It can't be the case that you have to read the whole discussion to participate. That doesn't scale.

The goal of the discussion should be to identify all the pros and cons and tradeoffs involved in the decision. Often that makes the decision clear, but not always, especially for large ones.

We've always collected these pros and cons informally; at best we occasionally write a discussion summary. For large changes it may make sense to write a formal, explicit “decision document” that lays out the pros, cons, and tradeoffs. Then the goal of the discussion is to complete this document. Someone who wants to participate in the discussion could start by reading the document and checking whether anything is left to add.

The current proposal process description hints at the discussion feeding back into the main proposal doc, but I think it would be clearer to have a separate document that is the discussion summary / inputs to the decision / tradeoffs.

Someone proposing a large change would be responsible for incorporating discussion into the design document, or else for finding someone who will.

The same kind of decision document could be written for design drafts (maybe a pre-decision document).

[smasher164]

Often times, digging through an extremely large issue for decision summaries to reference can be tedious. However, as you previously mentioned, Github doesn't have a way of pinning comments. Maybe an issue could have a corresponding external, canonical log of decision docs? That does however sound like some effort to maintain.

[lollipopman]

The very long discussion on the slog proposal is a great example of why having a summary doc for larger changes would be valuable for all people participating in a proposal discussion. I lost count of how many times I had to hit the "Load more..." button on that issue, in an attempt to discern whether my concern had already been voiced.