Skip to content

Commit 386f798

Browse files
authored
Contributing: Commit message advice (#24)
Adds advice on writing commit message to the contributing guide. This PR also acts as a test for the merging strategy to see if it has been setup correctly for smashing fixup commits. @Oghma feel free to add your suggestions as well.
1 parent 4e2c5fb commit 386f798

1 file changed

Lines changed: 13 additions & 2 deletions

File tree

CONTRIBUTING.md

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,23 @@
11
# Contributor's guide
22

3-
## Commit signing
3+
## Commits
4+
### Commit signing
45

56
Enable [commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
67

78
```sh
89
git config commit.gpgsign true
910
```
11+
12+
### Commit messages
13+
14+
Strive to write informative commit messages: a single line summary of the change and maybe a small exposition in the body of the message.
15+
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.
16+
17+
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.
18+
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.
19+
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.
20+
Fixup commits are also useful during reviews, as they maintain the chronological points of the discussion and will be squashed out when merging.
1021

1122
## Prerequisites
1223

@@ -114,4 +125,4 @@ But these 3 should be enough for the average application to identify bottlenecks
114125

115126
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).
116127
For Rayon-based parallel Rust code, we recommend Samply.
117-
It provides good profiling despite missing some multithreading details.
128+
It provides good profiling despite missing some multithreading details.

0 commit comments

Comments
 (0)