From bf4722d67af3fd6697d4922df069cd31e2858dd6 Mon Sep 17 00:00:00 2001 From: Dave Tucker Date: Thu, 20 Jul 2023 11:15:02 +0100 Subject: [PATCH] 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 --- .mergify.yml | 16 +++++ CODEOWNERS | 2 + CONTRIBUTING.md | 156 +++++++++++++++++++++++++++++++++++++----------- GOVERNANCE.md | 131 ++++++++++++++++++++++++++++++++++++++++ MAINTAINERS.md | 16 +++++ SECURITY.md | 13 ++++ 6 files changed, 300 insertions(+), 34 deletions(-) create mode 100644 CODEOWNERS create mode 100644 GOVERNANCE.md create mode 100644 MAINTAINERS.md create mode 100644 SECURITY.md diff --git a/.mergify.yml b/.mergify.yml index eeb756f8..760163eb 100644 --- a/.mergify.yml +++ b/.mergify.yml @@ -1,4 +1,6 @@ pull_request_rules: + # MERGE MANAGEMENT + - name: automatic merge for Dependabot pull request that pass CI conditions: - author=dependabot[bot] @@ -6,6 +8,20 @@ pull_request_rules: comment: message: "@dependabot merge" + - name: automatic merge conditions for main + conditions: + - "#approved-reviews-by>=2" + - "#review-requested=0" + - "#changes-requested-reviews-by=0" + - base=main + - label!=hold + - label!=work-in-progress + - check-success=DCO + - check-success=build-workflow-complete + actions: + merge: + method: merge + # REVIEW MANAGEMENT - name: ask alessandrod to review public API changes diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 00000000..e40bda79 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,2 @@ +* @aya-rs/aya-maintainers +aya/src/public-api.txt @alessandrod diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34ada6e8..a040af08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 + +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). diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..ed458ba1 --- /dev/null +++ b/GOVERNANCE.md @@ -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. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..3b0fc2e0 --- /dev/null +++ b/MAINTAINERS.md @@ -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 | ? | diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..26f25c55 --- /dev/null +++ b/SECURITY.md @@ -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.