Voting on technical issues

Voting on technical issues

Stan developers use the following voting system for making technical decisions in case of disagreement among developers. This is the version of the text approved by SGB in July 2020.

When should you call a vote?

A vote is only necessary if there is still disagreement on a major issue after ample discussion. For the most important decisions, a vote should be called even if there is no disagreement in order to create a record of the consensus.

We realize there is ambiguity on what constitutes a “major” issue or “ample” discussion. Some judgement is required on the part of the initial developer. A working definition is that an issue is “major” if it may create a substantial maintenance burden on other developers or introduces any user-facing changes that may be controversial (of course there is ambiguity about these definitions too). “Ample” discussion means that the issue has been raised, and other developers have had an opportunity to read, process, and chime in. If other developers think the vote was called too soon then they can vote “No”. A proposal voted down can be brought up for a vote again after subsequent discussion.

If you’re not sure if a vote is required, err on the side of collaborative decision making by calling a vote. However, keep in mind that voting is intended as a fallback and you should first make an attempt to understand and address the technical concerns through polite discussion.

Who can vote?

• Votes are open to developers contributing to the relevant module (see bullet point below) but any developer outside the module can force it to a developer-wide vote by objecting. Developers calling for a vote also have the ability to nominate multiple relevant repos initially.
• A module is a repository on stan-dev. (This is a starting point. Depending on how this goes and how often modules need to be grouped together this can be revisited.)
• The exception to this is for major changes to the Stan language, in which case:
  • The proposed change should be posted on Discourse to allow the entire community to comment
  • The voting will be open to all modules.
  • Note: this is for major user-facing language changes and does not pertain to implementation issues, which are the purview of the language module developers. An example of a major user-facing change is a totally new syntax for declaring arrays (New array declaration syntax). An example of a minor user-facing change/addition is vectorizing binary functions (https://github.com/stan-dev/stanc3/issues/643).
• If you are eligible to vote it is up to you whether or not to vote, but please only vote if you think you are sufficiently informed about the relevant issues.

How does voting work?

• Platform for voting can be any electronic voting system. The voting does not need to be anonymous. For example “poll” feature on Discourse (https://meta.discourse.org/t/how-to-create-polls/77548) can be used.

• The following procedure will be used:

  • Someone proposes a vote and contacts SGB
  • The SGB will appoint a vote coordinator. The vote coordinator will recommend to the SGB if the the vote should occur. If the SGB agree that the vote should occur, the vote coordinator will administer the vote process.
  • The vote coordinator sets up the post with the poll, notifies voters, and reports the results after the vote (the fact that a vote has been requested and the final outcome of the vote should be made public).
  • A poll is open for 2 weeks in order to give everyone enough time. If a lazy vote fails and a majority approval is required, please create a new poll and note that it is requesting majority approval.

• Three vote options are available:

  • +1: Agree
  • 0: Abstain (the default)
  • -1: Disagree (you must list your reasons for disagreement in a comment) (This can be adjusted if a particular topic in question can’t be expressed as a yes/no vote and requires more options.)

• Proposal phrasing: Please include a statement that makes it clear what it means to “agree” or “disagree.”

• Lazy vote: A binding agreement is reached when there is a minimum of one +1 and no -1s. In other words, if anyone is in favor and no one is against then the vote passes.

• Majority approval: If a vote does not pass after a lazy vote, then the issue will require majority approval, where a binding agreement is reached when there are at least two +1s and more +1s than -1s. However, majority approval should be considered a last resort. The aim should be to reach rough consensus through discussion. To facilitate reaching rough consensus, voters are allowed to change their vote during the voting window if they change their minds.

• Every voter’s vote has equal weight and each person can only cast one vote on a given call. (The developer bringing up a topic for a vote can also cast their vote.)

Arbitration

The voting procedure is intended to help resolve developer disagreement but it is possible for disagreement to happen about the process itself. In this case there is the option for arbitration, which works as follows.

• If at least 3 developers consider any part of the process leading to a particular vote problematic, they may ask the SGB to arbitrate. An arbitration request stops the voting period if it already started.
• The SGB may designate a community member to serve as an arbiter either for a specific case or to generally handle all arbitration requests for a module. The arbiter will act on behalf of the SGB and notify the SGB of the resolution of any arbitration.
• The arbiter/SGB will consult all parties involved and then make a final decision on how the vote should proceed. That is, the arbiter/SGB will not decide the technical issue itself, but rather resolve issues related to the process, e.g., when a vote is called, the order of voting on multiple proposals, the final wording of the proposal, etc.