diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..38853e515 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,51 @@ + + +# Summary + + +# Related Issues + + +# 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 `./clippy.sh`. +- [ ] Unit tests are passing locally with `cargo test`. +- [ ] The [Integration tests] are passing locally. +- [ ] I have blessed any API changes with `cargo xtask public-api --bless`. + +[Integration tests]: https://github.com/aya-rs/aya/blob/main/test/README.md + +# (Optional) What GIF best describes this PR or how it makes you feel? diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 000000000..7f0dcd7df --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1 @@ +* @aya-rs/aya-maintainers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f2cb6a81..7b8d58e92 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,112 @@ -# 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 +* Community 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 an approval from at least one maintainer, your PR will + be merged. + +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 +117,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 +137,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 new file mode 100644 index 000000000..a8f8cce90 --- /dev/null +++ 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 diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 000000000..d1a36f63c --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,27 @@ +# 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. + +We use MAINTAINERS.md to track active maintainers and emeritus maintainers +rather than relying solely on GitHub teams. This codifies the process for +adding and removing maintainers as well, provides transparency, and leaves +an audit trail in the git history. + +## Active Maintainers + +- @ajwerner +- @alessandrod +- @astoycos +- @dave-tucker +- @davibe +- @marysaka +- @tamird +- @vadorovsky + +## Emeritus Maintainers + +None diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..49929d5c7 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +## Supported Versions + +No released versions of aya or its 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] 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. + +[Private Vulnerability Reporting Feature]: https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability