consensus decision making

src/SUMMARY.md

@@ -15,6 +15,9 @@
       - [Stabilized](./initiatives/process/stages/stabilized.md)
       - [Inactive](./initiatives/process/stages/inactive.md)
   - [FAQ](./initiatives/faq.md)
+- [Decision process and principles](./decision_process.md)
+  - [Decision process examples](./decision_process/examples.md)
+  - [Decision process reference](./decision_process/reference.md)
 - [Lang team "how to" guide](./how_to.md)
   - [Nominate an issue](./how_to/nominate.md)
   - [Propose an initiative](./how_to/propose.md)

src/decision_process.md

@@ -0,0 +1,51 @@
+This section documents the work-in-progress Rust language team decision
+process. This process, and the `rustbot` tooling to support it, does not yet
+have a finished implementation. This document serves to explain the intended
+process, for the purposes of ongoing implementation.
+
+## Prioritized principles of Rust team consensus decision-making
+
+These are in order of priority. They're intended to be general enough that they
+could apply to any Rust governance team, not just the language team.
+
+- **Treasure dissent.** When someone raises a concern, that's a chance to
+  improve the design, and to discover and explore underlying values. Dissent
+  should be an amicable, cooperative process.
+- **Understand and cooperatively resolve concerns.** We cannot resolve a
+  concern without first understanding it, including the underlying values
+  motivating it. We should demonstrate that understanding by documenting the
+  concern. We should consider the tradeoffs and the impacts on users, through
+  the Rust design principles. We should seek out and favor satisfying solutions
+  (those that satisfy everyone's values) over
+  [satisficing](https://en.wikipedia.org/wiki/Satisficing) solutions (those
+  that are just good enough for people to accept them as a compromise among
+  conflicting values, without actually being happy with the outcome).
+- **Don't force an irreversible decision.** We should make as many decisions
+  reversible as possible. Even when a decision seems irreversible (e.g.,
+  stabilization), we should strive to find a subset that still allows
+  addressing the use case, or a subset that will support evaluation and
+  data-gathering to enable making the decision in the future. If that's not
+  possible, consider the null alternative; not making a change should always be
+  the easier path, and the burden of proof to override a concern on an
+  irreversible decision should be high.
+- **Value expertise.** When cooperatively resolving a concern, or when
+  considering overriding a concern, carefully weigh the advice and
+  recommendations of experts. This includes team advisors, domain experts, and
+  the owners or members of relevant initiatives.
+- **Recording reasoning helps ensure good, consistent decisions over time.**
+  Even if we decide not to sustain an objection, we should always record the
+  objection and the reasons for our decision as a "dissent", as well as any
+  unresolved questions for evaluation later in the process. The team member who
+  raised the objection has the perogative to author that dissent and frame the
+  unresolved questions (within reason).
+- **Consensus doesn't mean unanimity.** Consensus means everyone is heard and
+  understood, and all concerns are addressed (even those not treated as
+  blocking), and the team finds the outcome reasonable. Consensus does not mean
+  everyone agrees completely.
+
+## Consensus decision-making process
+
+First, see [some examples of the decision-making process in
+action](./decision_process/examples.md). Then, read the [decision process
+reference](./decision_process/reference.md) for the full process and the
+`rustbot` tooling to support it.

src/decision_process/examples.md

@@ -0,0 +1,297 @@
+# Examples of the decision-making process in action
+
+## Reversible decision: merging a proposal
+
+The process is best described by example. Suppose that there is a pending lang
+team proposal, and a lang team member would like to serve as the liaison. They
+contact the team leads and receive the go-ahead. They can then write:
+
+> @rustbot merge
+>
+> I propose to merge this proposal. I think it will be a great addition to
+> Rust!
+
+This indicates that they would like to merge the proposal. At the moment, there
+is no decision pending, so rustbot would add a comment that looks like the
+following:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member places a "hold" on the decision (or
+> cancels it).
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | |
+> | @Grace | |
+> | @Niklaus | |
+
+As the comment says, the PR is now in "pending decision" state, with Alan
+having kicked off the process with a proposal to merge. Alan's status of
+**merge** will link to his comment.
+
+Now, for this particular proposal, Barbara has a concern. She thinks that the
+proposal has overlooked an important consideration. She writes a comment:
+
+> @rustbot hold
+>
+> Did you consider reversing the polarity? Or the impact on the flux capacitor?
+
+At this point, rustbot updates the state:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | **hold** |
+> | @Grace | |
+> | @Niklaus | |
+
+Alan is currently busy at work, though, so by by the time that he and Barbara
+get a chance to talk, 11 days have passed. (Alan and Barbara receive a ping
+from rustbot after a week or so.) Once they get a chance to talk, Alan
+fully addresses Barbara's concern, so Barbara posts:
+
+> @rustbot merge
+
+The comment is updated:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | ~~hold~~ **merge** |
+> | @Grace | |
+> | @Niklaus | |
+
+Barbara's previous ~~hold~~ status links to her previous comment setting her
+status to `hold`, and her current **merge** status links to her more recent
+comment setting her status to `merge`.
+
+At this point, all the statuses are either empty, **abstain**, or **merge**,
+and more than 10 days have passed since the FCP started. Therefore, it
+completes immediately.
+
+## Authoring an RFC (illustration of `rustbot restart`)
+
+After some time, the proposal is completed and an RFC is proposed. This is a
+reversible decision. Alan, as the liaison, proposes to merge the RFC with
+`@rustbot merge`, and the decision making process proceeds as above.
+
+This time, Niklaus has a concern:
+
+> @rustbot hold
+>
+> I have not had time to read this yet! Give me a bit of time to write it up.
+
+After 7 days have passed, rustbot writes to her:
+
+> @Niklaus, I see you have placed a hold but 7 days have passed. Are you any
+> closer to reaching a decision? (cc @Alan)
+
+This continues for a week or two while Alan and Niklaus play "email tag". In
+the interim, Barbara decides she agrees with the RFC, so she uses `@rustbot
+merge` as well. The status now looks like this:
+
+> Hello! @Alan has proposed to merge this PR. This is a **reversible
+> decision**, which means that it will be affirmed once the "final comment
+> period" of 10 days have passed, unless a team member pauses or suspends the
+> decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | **merge** |
+> | @Grace | |
+> | @Niklaus | **hold** |
+
+Eventually, Alan and Niklaus find a time to discuss, and Alan agrees that
+Niklaus's concerns are valid, so he makes some major edits to the RFC. Given
+that the RFC is completely different, he decides to restart the clock and
+writes:
+
+> @rustbot restart
+
+This clears the state of all team members (preserving the history) and begins
+the clock anew. rustbot also pings the relevant team members:
+
+> Dear @rust-lang/team, @Alan has restarted the clock!
+
+The status now looks like this:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | ~~merge~~ |
+> | @Grace | |
+> | @Niklaus | ~~hold~~ |
+
+Barbara can use `@rustbot merge` to re-affirm her **merge** status, and Niklaus
+can use `@rustbot merge` to set his own status to **merge** since he agrees
+with the resolution of his concern.
+
+## Authoring an RFC continued (Overriding a concern)
+
+At this point, Grace has a concern, and explains that concern in detail:
+
+> @rustbot hold
+>
+> I've thought about this a lot, and I don't think we should do this. Now that
+> I see the syntax used in practice, I feel like if we do this it'll have an
+> adverse effect on the ecosystem...
+
+The status now looks like this:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | ~~merge~~ **merge** |
+> | @Grace | **hold** |
+> | @Niklaus | ~~hold~~ **merge** |
+
+Niklaus reads this message. He feels he understands the concern well, and
+agrees that this point hasn't yet been considered:
+
+> @rustbot hold
+>
+> I agree. I think we should take more time to evaluate alternative syntaxes.
+> What about...
+
+Over the course of a few subsequent meetings and side conversations, Grace and
+other team members discuss the concern further; the initiative owner also
+considers the concern, and raises it with others working on the initiative.
+
+The owner of the initiative updates the RFC to include a discussion of a couple
+of alternative syntax proposals. The owner recommends a slightly modified
+version of the originally proposed syntax, and outlines criteria that they feel
+the syntax should meet in order to support the use case.
+
+Grace agrees that her concern has been understood, but does not agree with the
+proposed syntax. Grace feels the new proposal is an improvement, but her
+concern remains.
+
+Niklaus feels that the team has understood Grace's concern, and furthermore,
+that the updated proposal addresses Grace's concern:
+
+> @rustbot merge
+>
+> I appreciate the potential impact this may have on the ecosystem. However, I
+> feel that as now described in section XYZ of the RFC, the value of A
+> outweighs the risk of B, and we've now mitigated the potential risk by...
+
+(Notice that while Niklaus feels that the team has understood Grace's concern,
+he does not use "We" in his response, and does not imply that his summary
+represents the entire team. Niklaus is just withdrawing his own support for the
+concern.)
+
+At this point, the entire team other than Grace agrees that the proposal should
+move forward:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | ~~merge~~ **merge** |
+> | @Grace | **hold** |
+> | @Niklaus | ~~hold~~ ~~merge~~ ~~hold~~ **merge**|
+
+(We'll assume, for this example, that Grace does not manage to convince anyone
+else.)
+
+Grace takes some time, working with the RFC author, to add a dissent, including
+a specific unresolved question.
+
+Grace then writes a comment containing `@rustbot dissent`. (If necessary, or if
+Grace would prefer, another team member may issue `@rustbot @grace dissent` on
+her behalf.) The status now looks like this:
+
+> Hello! @Alan has proposed to merge this. This is a **reversible decision**,
+> which means that it will be affirmed once the "final comment period" of 10
+> days have passed, unless a team member pauses or suspends the decision.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | **merge** |
+> | @Barbara | ~~merge~~ **merge** |
+> | @Grace | ~~hold~~ **dissent** |
+> | @Niklaus | ~~hold~~ ~~merge~~ ~~hold~~ **merge**|
+
+Since all statuses are now either **merge** or **dissent** rustbot also posts a
+comment:
+
+> The final comment period has resolved, with a decision to **merge**.
+>
+> Note that this decision has dissents; please ensure these dissents have been
+> recorded for subsequent consideration.
+
+## Stabilizing a feature
+
+The feature has been implemented and is now eligible for stabilization. Alan
+writes a stabilization report and posts it, and then issues the command
+
+> @rustbot stabilize
+
+Rustbot recognizes that a "stabilization" decision is irreversible, so the
+template is a bit different:
+
+> Hello! @Alan has proposed to stabilize this. This is a **irreversible
+> decision**, which means that it will be affirmed once all members come to a
+> consensus and the "final comment period" of 10 days has passed.
+>
+> | Team member | State |
+> | --- | --- |
+> | @Alan | stabilize |
+> | @Barbara |  |
+> | @Grace |  |
+> | @Niklaus |  |
+
+This time, Barbara, Grace, and Niklaus must all explicitly provide a status
+before the decision can proceed. One by one, they join the PR. They must
+individually set their state using one of the rustbot commands.
+
+Niklaus reads this and comments with `@rustbot merge`. But then, Niklaus uses
+the feature and discovers a crucial flaw. He posts a comment:
+
+> @rustbot close
+>
+> After more testing, I believe this is not ready for stabilization. I have
+> found that it doesn't work at all like the specification in the case of foo!
+> This seems closely related to Grace's concern on the RFC; I think if we
+> stabilize at this point we may indeed harm the ecosystem...
+
+Other team members test as well, and find that Niklaus is right. Alan changes
+his status using `@rustbot close`, and Grace (with some relief) sets the same
+status.
+
+Once everyone has changed their status, rustbot posts a comment:
+
+> The final comment period has resolved, with a decision to **close**.
+
+(Note: Since `close` is an inherently mutable status (a PR can always be
+reopened), rustbot can observe that everyone has set a mutable status, and will
+start treating the decision as mutable; this means the final comment period can
+end even if Barbara hasn't responded yet.)
+
+This may not be the end of this feature's consideration, and the concern might
+get resolved in many different ways. The initiative owner might need to do some
+additional design work on how to solve the original use case and address the
+concern; implementers may find a way to address the concern by improving the
+implementation; or the team may change their mind.