Writing good Commit Messages

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:

• Add a issue number at the end of the line when available as in “#234”

• 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 number. If this was a trivial change it may not have one though. If it had one a you would use #156 as a suffix to the first line.

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>