Propose guidance around contentious decisions. #8438
Conversation
[ci skip] # Documentation-only change.
src/docs/committers.md
Outdated
| Contentious Decisions | ||
| --------------------- | ||
|
|
||
| To help address cases where consensus cannot been reached even after extended discussion, committers |
There was a problem hiding this comment.
typo: cannot been reached
| countdown if any new votes arrive before that period has elapsed). | ||
|
|
||
| When tallying the votes, only committer's votes will be counted: votes are counted using | ||
| <https://en.wikipedia.org/wiki/Instant-runoff_voting> (the "last choice" alternative is eliminated |
There was a problem hiding this comment.
This makes me very very happy :)
There was a problem hiding this comment.
+1 for ranked-choice voting!
src/docs/committers.md
Outdated
| discussion, a committer may call a vote by creating a new thread on <pants-devel@googlegroups.com> | ||
| with a subject line of the form `[vote] Should We X for Y?`, and a body that presents a series | ||
| of the (pre-discussed) numbered choices. Because the topic will already have been extensively | ||
| discussed, the voting thread should _not_ be used for further discussion: instead, it should be |
There was a problem hiding this comment.
If an alternative option comes once the vote is called for, what would be the best place to put it? My hunch is that the right place is the original thread, and the voting thread should get invalidated and restarted, but that might lead to non-consensus for very long times.
There was a problem hiding this comment.
I think that's a reasonable strategy... will formalize.
src/docs/committers.md
Outdated
| discussed, the voting thread should _not_ be used for further discussion: instead, it should be | ||
| filled with responses containing only a list of the individual's ranked numerical choices (from | ||
| first choice to last choice in descending order). Individuals may change their votes by replying | ||
| again. |
There was a problem hiding this comment.
Does this mean that committers should not include their rationale for why they voted that way?
For example, choosing between Travis vs CircleCI:
Switch to CircleCI: 1
Stay with Travis: 2
vs.
Switch to CircleCI: 1, the costs are the most compelling reason.
Stay with Travis: 2, would be okay with staying with this.
vs. even more elaborate rationales why we voted this way.
(On this note, it could help to add an example to this doc.)
There was a problem hiding this comment.
Yes, it does mean that. The alternatives should already have been extensively discussed elsewhere.
There was a problem hiding this comment.
Got it. To make this extra clear, I'd change to this:
filled with responses containing only a list of the individual's ranked numerical choices (from
first choice to last choice in descending order), with no rationale included.
src/docs/committers.md
Outdated
| discussion, a committer may call a vote by creating a new thread on <pants-devel@googlegroups.com> | ||
| with a subject line of the form `[vote] Should We X for Y?`, and a body that presents a series | ||
| of the (pre-discussed) numbered choices. Because the topic will already have been extensively | ||
| discussed, the voting thread should _not_ be used for further discussion: instead, it should be |
src/docs/committers.md
Outdated
| To help address cases where consensus cannot been reached even after extended discussion, committers | ||
| may use a vote to reach a conclusion. |
There was a problem hiding this comment.
Committers are the only ones who can trigger a vote, right? Who can trigger a proposal with this structure? I advocate that anyone in the Pants community can propose something. If we agree, then add something like:
Even though committers are the only ones who may call for a vote, anyone in the Pants community is encouraged to propose changes, as described in the following paragraph.
There was a problem hiding this comment.
Anyone is able to send mail to pants-devel@, so I don't know if folks need explicit permission for that... this is more just to discourage folks who are not committers from attempting to start votes.
| first choice to last choice in descending order). Individuals may change their votes by replying | ||
| again. | ||
|
|
||
| When a thread has not received any new responses in three business days, the committer who called |
There was a problem hiding this comment.
Is there any expectation for the committer to publicize the vote beyond the original email? Should they message committers on Slack? Send followup emails?
If so:
During these three business days, the committer who called the vote should make a good-faith effort to ensure that all relevant stakeholders are aware of the vote, such as messaging other committers on Slack. While there is no expectation that every committer votes, we want everyone to be aware of the process.
Although with this wording, stakeholders is ambiguous. Perhaps change to all committers (or as close to all as feasible).
| the vote should reply to request any final votes within one business day (and restart the three day | ||
| countdown if any new votes arrive before that period has elapsed). | ||
|
|
||
| When tallying the votes, only committer's votes will be counted: votes are counted using |
There was a problem hiding this comment.
Can non-committers still vote?
When tallying the votes, only committer's votes will be counted, although non-committers are still encouraged to vote so that committers may better understand what other stakeholders think of the decision. Votes are counted using ...
| countdown if any new votes arrive before that period has elapsed). | ||
|
|
||
| When tallying the votes, only committer's votes will be counted: votes are counted using | ||
| <https://en.wikipedia.org/wiki/Instant-runoff_voting> (the "last choice" alternative is eliminated |
There was a problem hiding this comment.
+1 for ranked-choice voting!
# Delete this line to force a full CI run for documentation-only changes. [ci skip] # Documentation-only change.
|
This seems perfectly reasonable to me. |
| you are unsure of whether an issue is contentious, consider sending the mail anyway. | ||
|
|
||
| If it becomes clear that all concerns have been voiced, but that consensus cannot be reached via | ||
| discussion, a committer may call a vote by creating a new thread on <pants-devel@googlegroups.com> |
There was a problem hiding this comment.
Could we make it more clear here that this step is to be taken only in cases which have previously received discussion on pants-devel? The current reading seems like it could be interpreted as "making the initial thread on pants-devel is optional, but you can call a vote either way".
As suggested on the mailing list, this is a proposal for how we should resolve contentious items within the community.