Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal: add explicit decision doc for large changes #33791

rsc opened this issue Aug 22, 2019 · 2 comments

proposal: add explicit decision doc for large changes #33791

rsc opened this issue Aug 22, 2019 · 2 comments


Copy link

rsc commented Aug 22, 2019

#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).

@rsc rsc added this to the Proposal milestone Aug 22, 2019
Copy link

smasher164 commented Aug 22, 2019

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.

@ianlancetaylor ianlancetaylor added this to Incoming in Proposals (old) Jan 13, 2021
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Status: Incoming

No branches or pull requests

4 participants