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

docs: add instruction how voting automation works #1155

Merged
merged 31 commits into from
Apr 25, 2024
Merged
Changes from 7 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
0cc25d9
Added voting.md file
AayushSaini101 Apr 9, 2024
f71e33a
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 9, 2024
2190d83
Merge branch 'master' into Issue-1093-B
derberg Apr 9, 2024
6cee4db
Merge branch 'master' into Issue-1093-B
derberg Apr 9, 2024
07e443f
Update voting.md
AayushSaini101 Apr 10, 2024
fe6c3b0
Update voting doc
AayushSaini101 Apr 10, 2024
4afd81c
Update voting.md
AayushSaini101 Apr 10, 2024
a6fac7e
Update voting.md
AayushSaini101 Apr 11, 2024
95b81aa
Update voting.md
AayushSaini101 Apr 11, 2024
1240bd7
Update voting.md
AayushSaini101 Apr 11, 2024
4292db2
Update voting.md
AayushSaini101 Apr 11, 2024
7bd2ed4
Update voting.md
AayushSaini101 Apr 11, 2024
697099b
Update voting.md
AayushSaini101 Apr 11, 2024
175319e
Update voting doc
AayushSaini101 Apr 12, 2024
82fa0c9
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 12, 2024
1921519
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 14, 2024
647d2f7
Improve suggestions
AayushSaini101 Apr 15, 2024
70de86e
Update voting.md
AayushSaini101 Apr 15, 2024
9926395
Rephrase git-vote to Git Vote
AayushSaini101 Apr 15, 2024
76991ab
Update voting.md
AayushSaini101 Apr 15, 2024
991f34e
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 15, 2024
f06f6a3
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 15, 2024
e15ae4a
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 17, 2024
5e44df1
Update voting.md
AayushSaini101 Apr 18, 2024
4f28b95
punctuation correction
thulieblack Apr 18, 2024
e3e42c3
Update voting.md
thulieblack Apr 18, 2024
b90b6e3
Merge branch 'master' into Issue-1093-B
asyncapi-bot Apr 19, 2024
1b7d67b
Update voting.md
AayushSaini101 Apr 19, 2024
c625991
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 22, 2024
07adb63
Merge branch 'master' into Issue-1093-B
AayushSaini101 Apr 23, 2024
e2c6600
Merge branch 'asyncapi:master' into Issue-1093-B
AayushSaini101 Apr 25, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions voting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
## Overview
derberg marked this conversation as resolved.
Show resolved Hide resolved

In the [search for the right governance model](https://www.asyncapi.com/blog/governance-motivation) we ended up defining a Technical Steering Committee (TSC) that can help make decisions that are related to the entire AsyncAPI Initiative and not only a specific repository. TSC voting is described in the official [Charter](https://github.com/asyncapi/community/blob/master/CHARTER.md#4-tsc-voting).

To make the voting process easier with proper automation we use [**git-vote**](https://github.com/cncf/gitvote) bot.

### Voting Location
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved

- Voting must take place only in [community](https://github.com/asyncapi/community) repository
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved
- Voting automation works only with GitHub Issues and Pull Requests
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved

Discussions should be used only for initial discussion, to brainstorm ideas or to get some initial support.

In the majority of cases topics we vote on introduce some new rules, some new ways of doing things. This means that in the majority of cases, the topic we vote on needs proper community documentation. We recommend that you use Pull Requests over Issues to run voting on a topic where you provide context and final documentation.

### Voting Rules

* Only votes from [TSC members](https://www.asyncapi.com/community/tsc) are counted. You are still encouraged to participate in voting, even if your vote is not binding.
* TSC members have no less than 7 calendar days to vote. As a community, we did not set an exact voting deadline and only have a rule that you can translate into: "Just be nice and give people at least 7 days to get familiar with the topic so they can vote". Our automation is set for 4 weeks, to take into account all possible limitations related to holidays and other events.
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved
* The vote is completed when more than 50% voting are in favour.

### Voting Process

#### Start Voting

1. TSC member adds `/vote` comment to an Issue or a Pull Request.
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved
2. The Git Vote bot creates a comment with instructions on how the voting should be done. It is based on 👍🏼 , 👎🏼 and 👀 emojis. You can still put comments or suggestions.
3. AsyncAPI bot adds a `vote` label so later it is easier for us to extract information about voted topics and participation.
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved

#### Check Status

1. Anyone can add a `/check-vote` comment to an Issue or a Pull Request.
2. The Git Vote bot creates a comment with an update on how many binding votes were provided and how much is missing to reach the quorum.

### Cancel Voting

1. TSC member adds `/cancel-vote` comment to an Issue or a Pull Request.
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved
2. The Git Vote bot creates a comment.
3. The AsyncAPI bot removes the `vote` label.

### Finish Voting

There is no way to complete voting with a comment. It ends either when the majority of the positive voting is reached that is least >50% of the users with binding votes or the duration deadline ends.
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved
AayushSaini101 marked this conversation as resolved.
Show resolved Hide resolved

The Git Vote bot adds a comment that voting is completed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Git Vote bot adds a comment that voting is completed.
The Git Vote bot adds a comment that voting is completed.
### How to Get Notified About Voting
All TSC members are part of `tsc_members` team in GitHub. This team is always mentioned in voting. Notifications are based on this information. Whenever `tsc_members` is mentioned:
- Regular GitHub notification is triggered
- AsyncAPI bot drops a message in Slack in `#95_bot-tsc-members-mentioned channel` channel
- Dedicated email is sent to people that subscribed to TSC voting list. You do not have to be a TSC member to subscribe and learn about voting. Go to [TSC list on AsyncAPI website](https://www.asyncapi.com/community/tsc) and use subscription form from there.

I think we need to have it - added basing on comment from @smoya about notifying people about voting

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@derberg
Do we need to send notifications every day [ 28 days ] to the Slack channel as well as mail?

  • /vote command is executed to start sending notifications to the users
  • /cancel-vote is executed to stop sending notifications to the users.
  • When vote finished command is executed by git-vote bot stop sending notification in this case also

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smoya @derberg Created an issue to enable notification #1163. @derberg We can update the doc when the above issue is complete, I will work on this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, this is different

the section I add is about: notify voting in place

we do not have yet: remind those that did not vote, that will probably be another paragraph once we add automation

thanks for creating the issue!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@derberg How we can automate to check whether the person has voted or not in the last 3 Months? I guess we can create one more issue for this one

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh yes definitely we need automation for it, create issue - yes - please

should not be hard, we run GH query to list all issues and PRs with vote label added in last 3 months. Then we parse the voting comment from bot, the voting summary one, and see who did not vote, and do some magic calculation 😄

can be also that we do it on schedule. Every month run a query that summarize voting, like you know we maintain some markdown with votes, and list of folks who did not participate - advantage is that we can also "discover" if someone is close to deadline and send a "warning" notification

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you add suggested section to document?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additionally, as I shared via DM on Slack, please clarify in the doc the following:

  1. As per the CHARTER, quorum is not needed. However, git-vote has technically limitations and quorum should be reached. Thats the reason we give 4 weeks to vote and we should chase people to vote in order to reach the quorum of people (people voting is >50). Please make a clear statement about this.
  2. What happens with abstentions. How are them counted in the voting system.
  3. Answering: are we able to still do a vote without git-vote (so manyally, as we are doing today) if we choose to do a voting without the need of quorum? Or rather should all votes go through git-vote from now on?

Loading