diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eab5d6a..9155cf8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,23 @@ # Contributor's guide -## Commit signing +## Commits +### Commit signing Enable [commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) ```sh git config commit.gpgsign true ``` + +### Commit messages + +Strive to write informative commit messages: a single line summary of the change and maybe a small exposition in the body of the message. +If you do write an exposition, include parts of it in the PR description and in the source code as well. This gives multiple avenues to find the motivation for the change. + +Avoid writing commit messages like "wip", "fix", or drawn-out commit messages that actually say nothing. Use fixup commits instead, as these can be automatically squashed, thereby keeping the log clean. +To make a fixup commit: `git commit --fixup SHA`, where SHA points to the commit hash where, looking back, you would have liked to have made this change in the first place. +When you publish the branch for review, do `git rebase --autosquash` beforehand and the history will be clean. This way you'll have chronological checkpoints while developing. Upon publishing, you'll have a clean commit history that tells a logically constructive story without odd backreferences to earlier points. +Fixup commits are also useful during reviews, as they maintain the chronological points of the discussion and will be squashed out when merging. ## Prerequisites @@ -106,4 +117,4 @@ But these 3 should be enough for the average application to identify bottlenecks For async-rust we also recommend: [Tracing](https://crates.io/crates/tracing), [Tokio-Console](https://crates.io/crates/tokio-console), and [Oha](https://crates.io/crates/oha). For Rayon-based parallel Rust code, we recommend Samply. -It provides good profiling despite missing some multithreading details. \ No newline at end of file +It provides good profiling despite missing some multithreading details.