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