You could be fixing a typo somewhere or churning out an entirely new feature - all of it is welcome. There are, however, certain guidelines we'd like for contributors to follow.
Commit messages guidelines
Commit messages are code themselves. They document the changes being and should be well explained. With that in mind, here's an example of a good commit:
main.go: move config parsing to config.go Configuration parsing should be in its own file as main.go was getting quite large. Closes https://gitlab.com/commento/commento-ce/issues/42
This shortlog straight away tells us several things: we're making this change in
main.go, this change is moving code out of
config.go, and the code being moved out is the configuration parsing part.
Here's an example of a bad commit shortlog:
This doesn't tell us much apart from the fact that the commit is fixing tests. Which file's tests are being fixed? Which individual test is being changed? What was wrong before? Why is the new behavior the correct one?
- Each commit should be atomic: a commit must do one thing only. If a change has multiple logically different segments, each should probably be in its own commit.
- The commit shortlog must be of the form
context: description(all lower case), where
contextis the filename or the directory being changed. For example, if you're making a change to
main.go, the shortlog must be prefixed with it. If your change spans several files and directories, it's up to you; use something logical.
- The commit shortlog should be in imperative mood. For example, use "main.go: Move config..." instead of "main.go: Moved config...", as if you're giving orders to the codebase to change its behaviour.
- Try to limit the commit shortlog and body to under 50 and 72 characters in length, respectively. Feel free to be as descriptive as possible in the commit body by wrapping your text and using multiple lines and paragraphs.