What is good commit message? We want to avoid this: https://xkcd.com/1296/
Read these articles:
- by @cbeams How to Write a Git Commit Message
- this README from Linus Torvalds https://github.com/torvalds/subsurface-for-dirk/blob/0f58510ce0244513521296b75281fcc32f72a931/README#L73
- from the Git book: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
The main style points are these:
Subject:
- Prefer full issue URLs (e.g.
https://github.com/aboutcode-org/aboutcode/issues/234) to keep references valid if code moves to another repo. - Shorthand
#234is acceptable only when the work is guaranteed to remain in the same repository. - Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line: you are giving orders to the codebase
Body:
- Separate subject from body with a blank line
- Wrap the body at 72 characters. Use only spaces for formatting, not tabs.
- Use the body to explain what and why vs. how
- use bullets with a * if needed
- Add a Reported-by: if needed
- End your message with a Signed-off-by: prefixed by a blank line
Other comments:
We like to suffix the subject line with an issue reference. Use the full URL by
default; shorthand #156 only if the commit will stay in the same repository.
We like to tell why the commit is there and use an imperative style, like if you were giving an order to the codebase with your commit:
e.g rather than : Minor fix for unnecessary operations. may be Remove
unnecessary operations #123 or:
Remove unnecessary operations #123
* If the ts timestamp does not exist, do not compare with old one.
You need to add a signoff to your commit. So the final message would have looked like this:
Remove unnecessary operations #123
* If the ts timestamp does not exist, do not compare with old one.
Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>