Add project governance documentation

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 · Mar 6, 2025 · c8e408b · c8e408b
1 parent 73a34e1
commit c8e408b
Show file tree

Hide file tree

Showing 6 changed files with 355 additions and 37 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,44 @@
+<!--
+    Thank you for your contribution to Aya! 🎉
+
+    For Work In Progress Pull Requests, please use the Draft PR feature.
+
+    Before submitting a Pull Request, please ensure you've done the following:
+     - 📖 Read the Forem Contributing Guide: https://github.com/aya-rs/aya/blob/main/CONTRIBUTING.md
+     - 📖 Read the Forem Code of Conduct: https://github.com/aya-rs/aya/blob/main/CODE_OF_CONDUCT.md
+     - 👷‍♀️ Create small PRs. In most cases this will be possible.
+     - ✅ Provide tests for your changes.
+     - 📝 Use descriptive commit messages.
+     - 📗 Update any related documentation.
+
+-->
+
+# Description
+<!--- Describe your changes in detail -->
+
+# Related Issues
+<!--
+For example:
+
+- Closes: #1234
+- Relates To: #1234
+-->
+
+# Added/updated tests?
+
+_We strongly encourage you to add a test for your changes._
+
+- [ ] Yes
+- [ ] No, and this is why: _please replace this line with details on why tests
+      have not been included_
+- [ ] I need help with writing tests
+
+# Checklist
+
+- [ ] Rust code has been formatted with `cargo +nightly fmt`
+- [ ] All clippy lints have been fixed - you can find failing lints with `cargo +nightly clippy`
+- [ ] Unit tests are passing locally with `cargo test`
+- [ ] Integration tests are passing locally
+
+# (Optional) What GIF best describes this PR or how it makes you feel?
+<!--- Go to https://giphy.com/ and find a gif that fits your PR. Copy-paste the gif here -->
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -0,0 +1 @@
+* @aya-rs/aya-maintainers
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,67 +1,103 @@
-# Contributing to Aya
+# Contributing Guide
 
-Thanks for your help improving the project!
+* [New Contributor Guide](#contributing-guide)
+  * [Ways to Contribute](#ways-to-contribute)
+  * [Find an Issue](#find-an-issue)
+  * [Ask for Help](#ask-for-help)
+  * [Pull Request Lifecycle](#pull-request-lifecycle)
+  * [Pull Request Checklist](#pull-request-checklist)
+  * [Documentation Style](#documentation-style)
 
-## Reporting issues
+Welcome! We are glad that you want to contribute to our project! 💖
 
-If you believe you've discovered a bug in aya, please check if the bug is
-already known or [create an issue](https://github.com/aya-rs/aya/issues) on
-github. Please also report an issue if you find documentation that you think is
-confusing or could be improved.
+As you get started, you are in the best position to give us feedback on areas of
+our project that we need help with including:
 
-When creating a new issue, make sure to include as many details as possible to
-help us understand the problem. When reporting a bug, always specify which
-version of aya you're using and which version of the linux kernel.
+* Problems found during setting up a new developer environment
+* Gaps in our Quickstart Guide or documentation
+* Bugs in our automation scripts
 
-## Documentation
+If anything doesn't make sense, or doesn't work when you run it, please open a
+bug report and let us know!
 
-If you find an API that is not documented, unclear or missing examples, please
-file an issue. If you make changes to the documentation, please read
-[How To Write Documentation] and make sure your changes conform to the
-format outlined in [Documenting Components].
+## Ways to Contribute
 
-[How To Write Documentation]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
-[Documenting Components]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components
+We welcome many different types of contributions including:
 
-If you want to make changes to the Aya Book, see the readme in the
-[book repository].
+* New features
+* Builds, CI/CD
+* Bug fixes
+* Documentation
+* Issue Triage
+* Answering questions on [Discord]
+* Web design
+* Communications / Social Media / Blog Posts
+* Release management
 
-[book repository]: https://github.com/aya-rs/book
+Not everything happens through a GitHub pull request. Please come to our
+[Discord] and let's discuss how we can work together.
 
-## Fixing bugs and implementing new features
+## Find an Issue
 
-Make sure that your work is tracked by an issue or a (draft) pull request, this
-helps us avoid duplicating work. If your work includes publicly visible changes,
-make sure those are properly documented as explained in the section above.
+Issues labelled as ["good first issue"] are suitable for new
+contributors. They provide extra information to help you make your first
+contribution.
 
-### Running tests
+Issues labelled as ["help wanted"] are usually more difficult. We
+recommend them for people who aren't core maintainers, but have either made some
+contributions already or feel comfortable with starting from more demanding
+tasks.
 
-Run the unit tests with `cargo test`. See [Aya Integration Tests] regarding
-running the integration tests.
+Sometimes there won’t be any issues with these labels. That’s ok! There is
+likely still something for you to work on. If you want to contribute but you
+don’t know where to start or can't find a suitable issue, you can reach out to
+us on [Discord] and we will be happy to help.
 
-[Aya Integration Tests]: https://github.com/aya-rs/aya/blob/main/test/README.md
+Once you see an issue that you'd like to work on, please post a comment saying
+that you want to work on it. Something like "I want to work on this" is fine.
+
+## Ask for Help
+
+The best way to reach us with a question when contributing is to ask on:
+
+* The original GitHub issue
+* Our [Discord]
+
+## Pull Request Lifecycle
+
+Pull requests are managed by Mergify.
+
+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!
+1. Once it is passing all CI checks, a maintainer will review your PR and you may be asked to make changes.
+1. When you have received at two approving reviews from a maintainer, your PR will be merged automiatcally.
+
+In some cases, other changes may conflict with your PR. If this happens, you will get notified by a comment in the issue that your PR requires a rebase, and the `needs-rebase` label will be applied. Once a rebase has been performed, this label will be automatically removed.
 
-### Commits
+## Logical Grouping of Commits
 
 It is a recommended best practice to keep your changes as logically grouped as
 possible within individual commits. If while you're developing you prefer doing
 a number of commits that are "checkpoints" and don't represent a single logical
 change, please squash those together before asking for a review.
+When addressing review comments, please perform an interactive rebase and edit commits directly rather than adding new commits with messages like "Fix review comments".
 
-#### Commit message guidelines
+## Commit message guidelines
 
 A good commit message should describe what changed and why.
 
 1. The first line should:
-    - Contain a short description of the change (preferably 50 characters or less,
+    * Contain a short description of the change (preferably 50 characters or less,
       and no more than 72 characters)
-    - Be entirely in lowercase with the exception of proper nouns, acronyms, and
+    * Be entirely in lowercase with the exception of proper nouns, acronyms, and
       the words that refer to code, like function/variable names
-    - Be prefixed with the name of the sub crate being changed
+    * Be prefixed with the name of the sub crate being changed
 
     Examples:
-    - `aya: handle reordered functions`
-    - `aya-bpf: SkSkbContext: add ::l3_csum_replace`
+    * `aya: handle reordered functions`
+    * `aya-bpf: SkSkbContext: add ::l3_csum_replace`
 
 1. Keep the second line blank.
 1. Wrap all other lines at 72 columns (except for long URLs).
@@ -72,8 +108,8 @@ A good commit message should describe what changed and why.
 
    Examples:
 
-   - `Fixes: #1337`
-   - `Refs: #1234`
+   * `Fixes: #1337`
+   * `Refs: #1234`
 
 Sample complete commit message:
 
@@ -92,3 +128,32 @@ nicely even when it is indented.
 Fixes: #1337
 Refs: #453, #154
 ```
+
+## Pull Request Checklist
+
+When you submit your pull request, or you push new commits to it, our automated
+systems will run some checks on your new code. We require that your pull request
+passes these checks, but we also have more criteria than just that before we can
+accept and merge it. Theses requirements are described in the
+[Pull Request Template].
+
+It is recommended that you run the integration tests locally before submitting
+your Pull Request. Please see [Aya Integration Tests] for more information.
+
+## Documentation Style
+
+If you find an API that is not documented, unclear or missing examples, please
+file an issue. If you make changes to the documentation, please read
+[How To Write Documentation] and make sure your changes conform to the
+format outlined in [Documenting Components].
+
+If you want to make changes to the Aya Book, see the README in the
+[book repository].
+
+["good first issue"]: https://github.com/aya-rs/aya/labels/good%20first%20issue
+["help wanted"]: https://github.com/aya-rs/aya/labels/help%20wanted
+[Aya Integration Tests]: https://github.com/aya-rs/aya/blob/main/test/README.md
+[How To Write Documentation]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+[Documenting Components]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components
+[book repository]: https://github.com/aya-rs/book
+[Discord]: https://discord.gg/xHW2cb2N6G
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -0,0 +1,163 @@
+# Aya Project Governance
+
+The Aya project is dedicated to creating the best user experience when using
+eBPF from Rust, whether that's in user-land or kernel-land. This governance
+explains how the project is run.
+
+- [Values](#values)
+- [Maintainers](#maintainers)
+- [Becoming a Maintainer](#becoming-a-maintainer)
+- [Meetings](#meetings)
+- [Code of Conduct Enforcement](#code-of-conduct)
+- [Security Response Team](#security-response-team)
+- [Voting](#voting)
+- [Modifications](#modifying-this-charter)
+
+## Values
+
+The Aya project and its leadership embrace the following values:
+
+- Openness: Communication and decision-making happens in the open and is
+  discoverable for future reference. As much as possible, all discussions and
+  work take place in public forums and open repositories.
+
+- Fairness: All stakeholders have the opportunity to provide feedback and submit
+  contributions, which will be considered on their merits.
+
+- Community over Product or Company: Sustaining and growing our community takes
+  priority over shipping code or sponsors' organizational goals. Each
+  contributor participates in the project as an individual.
+
+- Inclusivity: We innovate through different perspectives and skill sets, which
+  can only be accomplished in a welcoming and respectful environment.
+
+- Participation: Responsibilities within the project are earned through
+  participation, and there is a clear path up the contributor ladder into
+  leadership positions.
+
+## Maintainers
+
+Aya Maintainers have write access to the all projects in the
+[GitHub organization]. They can merge their patches or patches from others.
+The list of current maintainers can be found at [MAINTAINERS.md].
+Maintainers collectively manage the project's resources and contributors.
+
+This privilege is granted with some expectation of responsibility: maintainers
+are people who care about the Aya project and want to help it grow and
+improve. A maintainer is not just someone who can make changes, but someone who
+has demonstrated their ability to collaborate with the team, get the most
+knowledgeable people to review code and docs, contribute high-quality code, and
+follow through to fix issues (in code or tests).
+
+A maintainer is a contributor to the project's success and a citizen helping
+the project succeed.
+
+The collective team of all Maintainers is known as the Maintainer Council, which
+is the governing body for the project.
+
+### Becoming a Maintainer
+
+To become a Maintainer, you need to demonstrate a commitment to the project, an
+ability to write quality code and/or documentation, and an ability to
+collaborate with the team. The following list is an example of the
+the kind of contributions that would be expected to be promoted to Maintainer
+status however there is no strict requirement for all points to be met:
+
+- Commitment to the project, as evidenced by:
+  - Participate in discussions, contributions, code and documentation reviews,
+    for 6 months or more.
+  - Perform reviews for 10 non-trivial pull requests.
+  - Contribute 10 non-trivial pull requests and have them merged.
+- Ability to write quality code and/or documentation.
+- Ability to collaborate with the team.
+- Understanding of how the team works (policies, processes for testing
+  and code review, etc).
+- Understanding of the project's code base and coding and documentation style.
+
+A new Maintainer must be proposed by an existing maintainer by opening a
+Pull Request on GitHub to update the MAINTAINERS.md file. A simple majority vote
+of existing Maintainers approves the application. Maintainer nominations will be
+evaluated without prejudice to employers or demographics.
+
+Maintainers who are selected will be granted the necessary GitHub rights.
+
+### Removing a Maintainer
+
+Maintainers may resign at any time if they feel that they will not be able to
+continue fulfilling their project duties. Resignations should be communicated
+via GitHub Pull Request to update the [MAINTAINERS.md] file. Approving
+resignations does not require a vote.
+
+Maintainers may also be removed after being inactive, failing to fulfill their
+Maintainer responsibilities, violating the Code of Conduct, or for other reasons.
+Inactivity is defined as a period of very low or no activity in the project
+for a year or more, with no definite schedule to return to full Maintainer
+activity.
+
+The process for removing a maintainer is for an existing maintainer to open
+a Pull Request on GitHub to update the [MAINTAINERS.md] file. The commit
+message should explain the reason for removal. The Pull Request will be
+voted on by the remaining maintainers. A 2/3 majority vote is required to
+remove a maintainer.
+
+Depending on the reason for removal, a Maintainer may be converted to Emeritus
+status. Emeritus Maintainers will still be consulted on some project matters
+and can be rapidly returned to Maintainer status if their availability changes.
+However, Emeritus Maintainers will not have write access to the project's
+repositories.
+
+The process for making an Emeritus Maintainer is the same as for removing a
+Maintainer, except that the [MAINTAINERS.md] file should be updated to reflect
+the Emeritus status rather than removing the Maintainer entirely.
+
+The process for returning an Emeritus Maintainer is via Pull Request
+to update the [MAINTAINERS.md] file. A simple majority vote of existing
+Maintainers approves the return.
+
+## Meetings
+
+There are no standing meetings for Maintainers.
+
+Maintainers may have closed meetings to discuss security reports
+or Code of Conduct violations. Such meetings should be scheduled by any
+Maintainer on receipt of a security issue or CoC report. All current Maintainers
+must be invited to such closed meetings, except for any Maintainer who is
+accused of a CoC violation.
+
+## Code of Conduct
+
+[Code of Conduct] violations by community members will be
+discussed and resolved on the private maintainer Discord channel.
+
+## Security Response Team
+
+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 at least once a year.
+
+The Security Response Team is responsible for handling all reports of security
+holes and breaches according to the [security policy].
+
+## Voting
+
+While most business in Aya is conducted by [lazy consensus], periodically the
+Maintainers may need to vote on specific actions or changes.
+A vote can be taken on the private developer Discord channel for security or
+conduct matters. Any Maintainer may demand a vote be taken.
+
+Most votes require a simple majority of all Maintainers to succeed, except where
+otherwise noted. Two-thirds majority votes mean at least two-thirds of all
+existing maintainers.
+
+## Modifying this Charter
+
+Changes to this Governance and its supporting documents may be approved by
+a 2/3 vote of the Maintainers.
+
+[GitHub organization]: https://github.com/aya-rs
+[Code of Conduct]: ./CODE_OF_CONDUCT.md
+[MAINTAINERS.md]: ./MAINTAINERS.md
+[security policy]: ./SECURITY.md
+[lazy consensus]: https://community.apache.org/committers/lazyConsensus.html