| 1 | # Contributing to `pin-init`
|
| 2 |
|
| 3 | Thanks for showing interest in contributing to `pin-init`! This document outlines the guidelines for
|
| 4 | contributing to `pin-init`.
|
| 5 |
|
| 6 | All contributions are double-licensed under Apache 2.0 and MIT. You can find the respective licenses
|
| 7 | in the `LICENSE-APACHE` and `LICENSE-MIT` files.
|
| 8 |
|
| 9 | ## Non-Code Contributions
|
| 10 |
|
| 11 | ### Bug Reports
|
| 12 |
|
| 13 | For any type of bug report, please submit an issue using the bug report issue template.
|
| 14 |
|
| 15 | If the issue is a soundness issue, please privately report it as a security vulnerability via the
|
| 16 | GitHub web interface.
|
| 17 |
|
| 18 | ### Feature Requests
|
| 19 |
|
| 20 | If you have any feature requests, please submit an issue using the feature request issue template.
|
| 21 |
|
| 22 | ### Questions and Getting Help
|
| 23 |
|
| 24 | You can ask questions in the Discussions page of the GitHub repository. If you're encountering
|
| 25 | problems or just have questions related to `pin-init` in the Linux kernel, you can also ask your
|
| 26 | questions in the [Rust-for-Linux Zulip](https://rust-for-linux.zulipchat.com/) or see
|
| 27 | <https://rust-for-linux.com/contact>.
|
| 28 |
|
| 29 | ## Contributing Code
|
| 30 |
|
| 31 | ### Linux Kernel
|
| 32 |
|
| 33 | `pin-init` is used by the Linux kernel and all commits are synchronized to it. For this reason, the
|
| 34 | same requirements for commits apply to `pin-init`. See [the kernel's documentation] for details. The
|
| 35 | rest of this document will also cover some of the rules listed there and additional ones.
|
| 36 |
|
| 37 | [the kernel's documentation]: https://docs.kernel.org/process/submitting-patches.html
|
| 38 |
|
| 39 | Contributions to `pin-init` ideally go through the [GitHub repository], because that repository runs
|
| 40 | a CI with lots of tests not present in the kernel. However, patches are also accepted (though not
|
| 41 | preferred). Do note that there are some files that are only present in the GitHub repository such as
|
| 42 | tests, licenses and cargo related files. Making changes to them can only happen via GitHub.
|
| 43 |
|
| 44 | [GitHub repository]: https://github.com/Rust-for-Linux/pin-init
|
| 45 |
|
| 46 | ### Commit Style
|
| 47 |
|
| 48 | Everything must compile without errors or warnings and all tests must pass after **every commit**.
|
| 49 | This is important for bisection and also required by the kernel.
|
| 50 |
|
| 51 | Each commit should be a single, logically cohesive change. Of course it's best to keep the changes
|
| 52 | small and digestible, but logically linked changes should be made in the same commit. For example,
|
| 53 | when fixing typos, create a single commit that fixes all of them instead of one commit per typo.
|
| 54 |
|
| 55 | Commits must have a meaningful commit title. Commits with changes to files in the `internal`
|
| 56 | directory should have a title prefixed with `internal:`. The commit message should explain the
|
| 57 | change and its rationale. You also have to add your `Signed-off-by` tag, see [Developer's
|
| 58 | Certificate of Origin]. This has to be done for both mailing list submissions as well as GitHub
|
| 59 | submissions.
|
| 60 |
|
| 61 | [Developer's Certificate of Origin]: https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
|
| 62 |
|
| 63 | Any changes made to public APIs must be documented not only in the commit message, but also in the
|
| 64 | `CHANGELOG.md` file. This is especially important for breaking changes, as those warrant a major
|
| 65 | version bump.
|
| 66 |
|
| 67 | If you make changes to the top-level crate documentation, you also need to update the `README.md`
|
| 68 | via `cargo rdme`.
|
| 69 |
|
| 70 | Some of these rules can be ignored if the change is done solely to files that are not present in the
|
| 71 | kernel version of this library. Those files are documented in the `sync-kernel.sh` script at the
|
| 72 | very bottom in the `--exclude` flag given to the `git am` command.
|