Add project governance! #679

dave-tucker · 2023-07-20T10:02:30Z

Adds documentation to explain:

Maintainer roles and responsibilities
Maintainer election/removal process
Pull Request Workflow (codified in the repo and enforced by Mergify)
Security Response Handling

Code changes:

Consolidates CI into a single pipeline - this gives us better execution control + allows us to block on only one CI status passing (build-workflow-complete).
Add cargo public-api for Aya, to ensure Alessandro reviews Aya API changes

TODO before merge:

Add Mergify to the repo
Add DCO bot to the repo

TODO after merge:

Enable the GitHub Security Reporting feature

This change is

netlify · 2023-07-20T10:02:59Z

✅ Deploy Preview for aya-rs-docs ready!

Name	Link
🔨 Latest commit	`bf4722d`
🔍 Latest deploy log	https://app.netlify.com/sites/aya-rs-docs/deploys/64c7bcef965aa100086a25cd
😎 Deploy Preview	https://deploy-preview-679--aya-rs-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

dave-tucker · 2023-07-20T10:23:39Z

@aya-rs/aya-maintainers This PR is aimed to solve some open issues around process. I borrowed a lot of this from bpfd 😏 which in turn was borrowed from some CNCF project or template or something.

MAINTAINERS.md is where we are all listed - please ensure your areas of responsibility, names and affiliations (if required) are accurate.

GOVERNANCE.md is where all the process around maintainers lives.
TL;DR

Be a good open source citizen
New maintainers are added via PR and requires a majority vote (either LGTM on PR or via Discord)
Maintainers are removed via PR and requires a 2/3 majority vote

The other important part is in CONTRIBUTING.md which outlines the Pull Request Workflow.
TL;DR:

At least 2 approving reviews are required for any PR.
Any PR that touches aya's public API needs explicit approval from @alessandrod in addition to one other maintainer review.

Since this is techincally a governance change, this PR will not merge until we have a 2/3 majority (that 6 of the 8 listed maintainers).

Feel free to discuss here or in Discord.

Explains how Maintainers are selected and their responsibilities. Explains the Pull Request review workflow. Adds config for Mergify to enforce this workflow. Signed-off-by: Dave Tucker <[email protected]>

vadorovsky · 2023-07-31T14:01:18Z

CONTRIBUTING.md


-Thanks for your help improving the project!
+* [New Contributor Guide](#contributing-guide)


I'm not a native English speaker, but is using capital letters everywhere necessary? I'd rather go with "Contributing guide", "Ways to contribute", "Find an issue" etc.

It's Title Case

vadorovsky · 2023-07-31T14:18:40Z

CONTRIBUTING.md

+We have good first issues for new contributors and help wanted issues suitable
+for any contributor. [good first issue](https://github.com/aya-rs/aya/labels/good%20first%20issue) has extra information to
+help you make your first contribution. [help wanted](https://github.com/aya-rs/aya/labels/help%20wanted) are issues
+suitable for someone who isn't a core maintainer and is good to move onto after
+your first pull request.


And here some sentences start without capital letters. 😛 Anyway, I would still rephrase it entirely.

Suggested change

We have good first issues for new contributors and help wanted issues suitable

for any contributor. [good first issue](https://github.com/aya-rs/aya/labels/good%20first%20issue) has extra information to

help you make your first contribution. [help wanted](https://github.com/aya-rs/aya/labels/help%20wanted) are issues

suitable for someone who isn't a core maintainer and is good to move onto after

your first pull request.

Issues labelled as ["good first issue"](https://github.com/aya-rs/aya/labels/good%20first%20issue)

are suitable for new contributors. They provide extra information to help you make your first

contribution.

Issues labelled as ["help wanted"](https://github.com/aya-rs/aya/labels/help%20wanted) are

usually more difficult. We recommend them for people who aren't core maintainers, but either

made some contributions already or feel comfortable with starting from more demanding tasks.

vadorovsky · 2023-07-31T14:19:32Z

CONTRIBUTING.md

+
+The best way to reach us with a question when contributing is to ask on:
+
+* The original github issue


vadorovsky · 2023-07-31T14:19:34Z

CONTRIBUTING.md

+The best way to reach us with a question when contributing is to ask on:
+
+* The original github issue
+* Our Discord


I'd include an invite link here (and everywhere we mention Discord).

vadorovsky · 2023-07-31T14:22:01Z

CONTRIBUTING.md

+
+    This is my commit message
+
+    Signed-off-by: Your Name <[email protected]>


Do we really want to require signoffs? @alessandrod

I don't mind it (I did it already in some of my PRs without even thinking about it), but we have a lot of not signed off commits. I'm also not a lawyer, but I don't think is really necessary for our licensing stuff?

tamird · 2023-07-31T14:53:47Z

.mergify.yml

  - name: automatic merge for Dependabot pull request that pass CI
    conditions:
      - author=dependabot[bot]
    actions:
      comment:
        message: "@dependabot merge"

+  - name: automatic merge conditions for main
+    conditions:
+      - "#approved-reviews-by>=2"


do we really need two reviewers?

Normally I'd say no....but I feel like with there being 10 approvers it won't have nearly as much effect on velocity and will ultimately help stability.

tamird · 2023-07-31T14:56:21Z

.mergify.yml

+      - base=main
+      - label!=hold
+      - label!=work-in-progress
+      - check-success=DCO


this makes it require the "signed off by" line? what does that do for us?

i think requiring signed commits is a much stronger stance (https://docs.github.com/en/[email protected]/authentication/managing-commit-signature-verification/about-commit-signature-verification) but also considerably more onerous.

I think we should just drop this requirement.

I feel signing your commits (just the sign-off line not commit verification) is just the Open source community standard tbh, I'm not against having it.

tamird · 2023-07-31T14:57:10Z

.mergify.yml

  - name: automatic merge for Dependabot pull request that pass CI
    conditions:
      - author=dependabot[bot]
    actions:
      comment:
        message: "@dependabot merge"

+  - name: automatic merge conditions for main


do we really want automatic merges? I'd really rather let a human being decide on the merge decision.

Perhaps we can allow folks to merge their own changes after they've been approved (pushing a new revision should require re-approval).

tamird · 2023-07-31T14:58:25Z

SECURITY.md

+
+## Supported Versions
+
+No released versions of aya or it's subprojects will receive regular security updates until a mainline release has been performed.


s/it's/its/

tamird · 2023-07-31T14:58:58Z

SECURITY.md

+## Supported Versions
+
+No released versions of aya or it's subprojects will receive regular security updates until a mainline release has been performed.
+A reported and fixed vulnerability will be included in the next minor release, which depending on the severity of the vulnerability may be immediate.


the line length here and in the other docs is inconsistent. can we pick one and use it everywhere?

Agreed. And I would suggest to use https://github.com/marketplace/actions/markdown-linting-action

tamird · 2023-07-31T15:01:16Z

MAINTAINERS.md

@@ -0,0 +1,16 @@
+# Maintainers


do we need this file? https://github.com/orgs/aya-rs/people is the source of truth (though we should make everyone's membership public)

tamird · 2023-07-31T15:02:53Z

GOVERNANCE.md

+To become a Maintainer you need to demonstrate the following:
+
+- commitment to the project:
+  - participate in discussions, contributions, code and documentation reviews, for 6 months or more,


these requirements seem overly rigid to me. we should keep this list as a reference, but i don't think it is helpful to frame it as strictly required.

tamird · 2023-07-31T15:04:00Z

GOVERNANCE.md

+Maintainers may resign at any time if they feel that they will not be able to
+continue fulfilling their project duties.
+
+Maintainers may also be removed after being inactive, failing to fulfill their


does this happen without a vote? who is the executor?

tamird · 2023-07-31T15:04:40Z

GOVERNANCE.md

+The Maintainers will appoint a Security Response Team to handle security reports.
+This committee may simply consist of the Maintainer Council themselves.  If this
+responsibility is delegated, the Maintainers will appoint a team of at least two
+contributors to handle it.  The Maintainers will review who is assigned to this


nit: double space after this period should be single

edit: there are a few others, please check them all

tamird · 2023-07-31T15:05:55Z

CONTRIBUTING.md

@@ -86,3 +155,22 @@ nicely even when it is indented.
 Fixes: #1337
 Refs: #453, #154
 ```
+
+## Pull Request Checklist


can we move some or all of this into the github pull request template?

astoycos

Thanks for doing this, just a couple nits/comments!

The one thing I don't see mentioned is the fact of joining the org WITHOUT becoming a maintainer. For contributors who just want to be able to manually assign issues and stuff it's nice to be made an org member I think. Something along the lines of what K8s calls a "member"

astoycos · 2023-08-01T20:36:30Z

.mergify.yml

  - name: automatic merge for Dependabot pull request that pass CI
    conditions:
      - author=dependabot[bot]
    actions:
      comment:
        message: "@dependabot merge"

+  - name: automatic merge conditions for main
+    conditions:
+      - "#approved-reviews-by>=2"


Normally I'd say no....but I feel like with there being 10 approvers it won't have nearly as much effect on velocity and will ultimately help stability.

astoycos · 2023-08-01T21:00:28Z

.mergify.yml

+      - base=main
+      - label!=hold
+      - label!=work-in-progress
+      - check-success=DCO


I feel signing your commits (just the sign-off line not commit verification) is just the Open source community standard tbh, I'm not against having it.

astoycos · 2023-08-01T21:01:45Z

CONTRIBUTING.md


-## Documentation
+If anything doesn't make sense, or doesn't work when you run it, please open a
+bug report and let us know!


We should probably add some issue templates along with this

i.e bug-report, enhancement-request, etc

astoycos · 2023-08-01T21:07:43Z

CONTRIBUTING.md

+before you submit your code:
+
+* That Rust code has been formatted with `cargo +nightly fmt` and that all clippy lints have been fixed - you can find failing lints with `cargo +nightly clippy`
+* That Go code has been formatted and linted


nit: not applicable here :)

astoycos · 2023-08-01T21:34:40Z

CONTRIBUTING.md

+* Answering questions on Discord
+* Web design
+* Communications / Social Media / Blog Posts
+* Release management


Community-management?

astoycos · 2023-08-01T21:36:11Z

CONTRIBUTING.md

+Our process is currently as follows:
+
+1. When you open a PR a maintainer will automatically be assigned for review
+1. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask!


NIT:

Suggested change

1. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask!

2. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask!

And so-on

astoycos · 2023-08-01T21:42:22Z

MAINTAINERS.md

+| [Mary](https://github.com/marysaka) | ? | Compatibility with older kernels |
+| [](https://github.com/ajwerner) | ? | ? |
+| [Tamir Duberstein](https://github.com/tamird) | ? | ? |
+| [Andrew Stoycos](https://github.com/astoycos) | Red Hat | ? |


astoycos · 2023-08-01T21:42:32Z

SECURITY.md

+## Supported Versions
+
+No released versions of aya or it's subprojects will receive regular security updates until a mainline release has been performed.
+A reported and fixed vulnerability will be included in the next minor release, which depending on the severity of the vulnerability may be immediate.


astoycos · 2023-08-01T21:43:32Z

GOVERNANCE.md

+status. Emeritus Maintainers will still be consulted on some project matters
+and can be rapidly returned to Maintainer status if their availability changes.
+
+## Meetings


I know no one is a fan but I feel like even a monthly or bi-monthly community meeting would be nice, I know it's hard to get together but as Aya grows more and more folks will get involved.

mergify · 2023-11-16T21:28:43Z

@dave-tucker, this pull request is now in conflict and requires a rebase.

mergify · 2024-02-06T12:37:00Z

@dave-tucker, this pull request is now in conflict and requires a rebase.

mergify · 2025-01-01T16:41:35Z

@dave-tucker, this pull request is now in conflict and requires a rebase.

dave-tucker force-pushed the governance branch from e7d2d2e to cb3e92f Compare July 20, 2023 10:04

dave-tucker requested a review from a team July 20, 2023 10:10

dave-tucker force-pushed the governance branch from cb3e92f to d9f9556 Compare July 20, 2023 10:15

dave-tucker force-pushed the governance branch 2 times, most recently from 5961b66 to c7ed48f Compare July 20, 2023 10:41

Add project governance documentation

bf4722d

Explains how Maintainers are selected and their responsibilities. Explains the Pull Request review workflow. Adds config for Mergify to enforce this workflow. Signed-off-by: Dave Tucker <[email protected]>

dave-tucker force-pushed the governance branch from c7ed48f to bf4722d Compare July 31, 2023 13:53

vadorovsky requested changes Jul 31, 2023

View reviewed changes

tamird reviewed Jul 31, 2023

View reviewed changes

astoycos reviewed Aug 1, 2023

View reviewed changes

mergify bot added the needs-rebase label Nov 16, 2023

mergify bot removed the needs-rebase label Jan 1, 2025

mergify bot added the needs-rebase label Jan 1, 2025


		Thanks for your help improving the project!
		* [New Contributor Guide](#contributing-guide)


		The best way to reach us with a question when contributing is to ask on:

		* The original github issue


		This is my commit message

		Signed-off-by: Your Name <[email protected]>


		## Supported Versions

		No released versions of aya or it's subprojects will receive regular security updates until a mainline release has been performed.

	1. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask!
	2. Make sure that your PR is passing CI - if you need help with failing checks please feel free to ask!

	\| [Andrew Stoycos](https://github.com/astoycos) \| Red Hat \| ? \|
	\| [Andrew Stoycos](https://github.com/astoycos) \| Red Hat \| Map API \|

Add project governance! #679

Are you sure you want to change the base?

Add project governance! #679

Conversation

dave-tucker commented Jul 20, 2023 • edited by tamird Loading

netlify bot commented Jul 20, 2023 • edited Loading

✅ Deploy Preview for aya-rs-docs ready!

dave-tucker commented Jul 20, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

astoycos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mergify bot commented Nov 16, 2023

mergify bot commented Feb 6, 2024

mergify bot commented Jan 1, 2025

dave-tucker commented Jul 20, 2023 •

edited by tamird

Loading

netlify bot commented Jul 20, 2023 •

edited

Loading