Automation flow for voting/decision-making (Martha's inspired)

[ebullient]

I am playing with this in https://github.com/commonhaus/automation

Suggestions/revisions improvements to this workflow idea are appreciated!

---

Voting

The CF follows an adapted form of Martha's Rules for decision making. This GitHub App helps automate the process.

The group that should be used to determine quorum must be specified in the item (a default group can be specified in the bot config).

Edit:

• Update issue/discussion with a phrase that loosely matches voting group @groupname (whitespace and punctuation variants are allowed between 'voting group' and the group name). This will tag/notify members of the relevant group.
• An HTML comment specifies what counts as approve, ok, revise: <!--vote::marthas approve="+1" ok="eyes" revise="-1" -->

General flow

stateDiagram-v2
    state if_state <<choice>>
    vopen: 🏷️ vote/open
    vquorum: 🏷️ vote/quorum
    vclosed: 🏷️ vote/closed
    revise: ① revise\n🏷️ vote/revise
    proceed: ② proceed\n🏷️ vote/proceed

    [*] --> vopen: labeled (👤 or 🤖)

    vopen --> vquorum: labeled (🤖)
    vopen --> vclosed: labeled (👤 or 🤖)
    vquorum --> vclosed: labeled (👤 or 🤖)

    vclosed --> if_state
    if_state --> revise : ❌ (🤖)
    if_state --> proceed : ✅ (🤖)
    revise -->  [*]
    proceed --> [*]

The item should be closed once the vote concludes.

• ① revise: If the vote fails, the sponsor can withdraw the proposal in its entirety or they can work on a revised proposal in a new item (discussion, issue, or PR) that addresses concerns, and start the process again.
• ② proceed: If the vote passes, the proposal is adopted. That could mean an idea is accepted and work begins on a PR, it could mean that a PR is merged (e.g. for policy or bylaw changes).

If work continues into a new item (either because it is revised, or because an approved proposal leads to a PR or other follow-on activity), cross-references should be added to both items.

Label usage

• 🏷️ vote/open - start tallying reactions

  When the vote is open, the bot will count reactions to the item (some caveats per type). It will append a section to the description with the current vote tally, including whether or not quorum has been reached. The bot will check for quorum any time the item is changed, or once an hour.

  (👤 or 🤖, TBD) This label could be applied directly by a human, or by the bot as a result of an action, like changing the category of a discussion or using a command.

• 🏷️ vote/quorum - quorum has been reached

  When quorum is reached, the bot will add a label to the item indicating that quorum has been reached.

  (🤖) This label should applied by the bot, not a human.

• 🏷️ vote/closed - vote is closed; stop counting, record results

  This label should be applied to close the vote. The bot will copy the vote summary into a comment and remove the vote/open, vote/quorum, and vote-closed labels.

  (👤 or 🤖, TBD) This label could applied by a human directly, or could be applied by the bot as a result of a command.

• 🏷️ vote/proceed - vote is closed; consensus: proceed

  When the vote is closed, the bot will copy the vote summary into a comment and add this label if the consensus is to proceed.

  (🤖) This label should applied by the bot, not a human.

• 🏷️ vote/revise - vote is closed; consensus: revise

  When the vote is closed, the bot will copy the vote summary into a comment and add this label if the consensus recommends revision.

  (🤖) This label should applied by the bot, not a human.

[kenfinnigan]

Overall the flow makes sense to me. Thanks for putting this together

I have a couple of questions:

• The diagram has a label of vote/disagree but your description has vote/revise. I'd prefer vote/revise, can the diagram be updated?
• vote/done to me doesn't necessarily mean it's finished, my brain goes to "Definition of Done" and thinking it's passed. Would vote/closed make it clear the voting process has ended and the votes will be tallied?
• Should votes have a maximum time length for them? This would enable the bot to add the vote completed label onto the issue after a set period of time since vote/open
• Will the bot have safeguards in place to reverse labels being added by humans that should only be added by itself? This would include vote/quorum, vote/proceed, and vote/revise.

[ebullient]

I stumbled around with terms for a bit.. Glad you like revise better. I do, too.

• Updated the above for disagree -> revise, and done -> closed.
• I do think we should have a max time to wait (lazy), but I want to wait until the notification process has settled before deciding on what feels like the right amount of time (and if that could be indicated in the item, e.g. an "urgent" label for special cases)
• I think the bot can look out for human-added bot-only labels.. which is why I was trying to indicate which would be bot-only. ;)

[kenfinnigan]

Sounds good, thanks

[kenfinnigan]

Though this isn't part of the by-laws, the pieces around it are.

Ok to close @ebullient or should we wait for additional input?

[ebullient]

I can leave this one open until I start writing it.. (soon. Now-ish, actually). Then I'll have more to ask.

[ebullient]

Note: edited above to match

I have a general flow for what happens when vote is open:

• In the item description:
  • Looks for "voting group @.... " to decide who the voting group is
  • Use an HTML comment to encode which reactions count to what, e.g.
    <!--vote::marthas approve="+1" ok="eyes" revise="-1" -->
• Counts reactions on the main issue in that voting group
• Discards duplicate votes (favors the most positive if you've responded more than once)
• Updates a single comment with the status of the vote (including errors if it can't determine the target voting group)

[ebullient]

Humans will need to be able to close a vote, and record the tally that is the result of a meeting (in the case the entire group does not respond electronically).