-
Notifications
You must be signed in to change notification settings - Fork 279
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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]>
- Loading branch information
1 parent
8778c4c
commit bf4722d
Showing
6 changed files
with
300 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
* @aya-rs/aya-maintainers | ||
aya/src/public-api.txt @alessandrod |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,61 +1,130 @@ | ||
# 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) | ||
* [Signoff Your Commits](#signoff-your-commits) | ||
* [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 | ||
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html and make sure | ||
your changes conform to the format outlined here | ||
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components. | ||
## Ways to Contribute | ||
|
||
If you want to make changes to the Aya Book, see the readme in the book repo | ||
https://github.com/aya-rs/book. | ||
We welcome many different types of contributions including: | ||
|
||
## Fixing bugs and implementing new features | ||
* New features | ||
* Builds, CI/CD | ||
* Bug fixes | ||
* Documentation | ||
* Issue Triage | ||
* Answering questions on Discord | ||
* Web design | ||
* Communications / Social Media / Blog Posts | ||
* Release management | ||
|
||
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. | ||
Not everything happens through a GitHub pull request. Please come to our | ||
[Discord](https://discord.gg/xHW2cb2N6G) and let's discuss how we can work | ||
together. | ||
|
||
### Running tests | ||
Run the unit tests with `cargo test`. See [Aya Integration Tests](https://github.com/aya-rs/aya/blob/main/test/README.md) regarding running the integration tests. | ||
## Find an Issue | ||
|
||
### Commits | ||
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. | ||
|
||
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. | ||
|
||
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. | ||
|
||
## Signoff Your Commits | ||
|
||
### DCO | ||
|
||
Licensing is important to open source projects. It provides some assurances that | ||
the software will continue to be available based under the terms that the | ||
author(s) desired. We require that contributors sign off on commits submitted to | ||
our project's repositories. The [Developer Certificate of Origin | ||
(DCO)](https://probot.github.io/apps/dco/) is a way to certify that you wrote and | ||
have the right to contribute the code you are submitting to the project. | ||
|
||
You sign-off by adding the following to your commit messages. Your sign-off must | ||
match the git user and email associated with the commit. | ||
|
||
This is my commit message | ||
|
||
Signed-off-by: Your Name <[email protected]> | ||
|
||
Git has a `-s` command line option to do this automatically: | ||
|
||
git commit -s -m 'This is my commit message' | ||
|
||
If you forgot to do this and have not yet pushed your changes to the remote | ||
repository, you can amend your commit with the sign-off by running | ||
|
||
git commit --amend -s | ||
|
||
## 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: validate program section names | ||
* aya-bpf: add dispatcher program test slot | ||
|
||
2. Keep the second line blank. | ||
3. Wrap all other lines at 72 columns (except for long URLs). | ||
|
@@ -66,8 +135,8 @@ A good commit message should describe what changed and why. | |
|
||
Examples: | ||
|
||
- `Fixes: #1337` | ||
- `Refs: #1234` | ||
* `Fixes: #1337` | ||
* `Refs: #1234` | ||
|
||
Sample complete commit message: | ||
|
||
|
@@ -86,3 +155,22 @@ 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. We recommend that you check the following things locally | ||
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 | ||
* That unit tests are passing locally with `cargo test` | ||
* That integration tests are passing locally `cargo xtask integration-test` | ||
|
||
## Documentation Style | ||
|
||
If you make changes to the documentation, please read | ||
[How To Write Documentation](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html)and make sure your changes conform to the format outlined [here]( | ||
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,131 @@ | ||
# 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](https://github.com/aya-rs). | ||
They can merge their patches or patches from others. The list of current maintainers | ||
can be found at [MAINTAINERS.md](./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 the following: | ||
|
||
- commitment to the project: | ||
- 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. | ||
|
||
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. | ||
|
||
A Maintainer may be removed at any time by a 2/3 vote of the remaining maintainers. | ||
|
||
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. | ||
|
||
## Meetings | ||
|
||
There are no standing meetings for Maintainers. | ||
|
||
Maintainers will also 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](./CODE_OF_CONDUCT.md) 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](./SECURITY.md). | ||
|
||
## Voting | ||
|
||
While most business in Aya is conducted by "[lazy consensus](https://community.apache.org/committers/lazyConsensus.html)", | ||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
# Maintainers | ||
|
||
See [CONTRIBUTING.md](./CONTRIBUTING.md) for general contribution guidelines. | ||
See [GOVERNANCE.md](./GOVERNANCE.md) for governance guidelines and maintainer responsibilities. | ||
See [CODEOWNERS](./CODEOWNERS) for a detailed list of owners for the various source directories. | ||
|
||
| Name | Employer | Areas of Expertise | | ||
| ---- | -------- | ------------------ | | ||
| [Alessandro Decina](https://github.com/alessandrod) | Contractor | Everything! | | ||
| [Michal Rostecki](https://github.com/vadorovsky) | Light Protocol | Aya Log, LSM | | ||
| [Dave Tucker](https://github.com/dave-tucker) | Red Hat | sys_bpf(), BTF, Networking and Tracing Programs, bppfs | | ||
| [Davide Bertola](https://github.com/davibe) | ? | bpf-linker, LLVM | | ||
| [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 | ? | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
# Security Policy | ||
|
||
## 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. | ||
|
||
## Reporting a Vulnerability | ||
|
||
To report a vulnerability, please use the [Private Vulnerability Reporting Feature](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability) | ||
on GitHub. We will endevour to respond within 48hrs of reporting. | ||
If a vulnerability is reported but considered low priority it may be converted into an issue and handled on the public issue tracker. | ||
Should a vulnerability be considered severe we will endeavour to patch it within 48hrs of acceptance, and may ask for you to collaborate with us on a temporary private fork of the repository. |