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

Open
rsc opened this issue Aug 22, 2019 · 1 comment

Comments

@rsc
Copy link
Contributor

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

@gopherbot gopherbot added the Proposal label Aug 22, 2019

@smasher164

This comment has been minimized.

Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.