Gerrit/Commit message guidelines

Commit message guidelines
Crafting the commit message is a very important step of your development work. The message is usually the first thing other developers will see, and the first line is used by various tools as a summary of your commit message. You will thus have a first line which is meaningful and short (≤50 characters) and then a detailed message fully explaining your patch, what you did, your design choice, possible culprit to look at, any test you could have done. Remember that people very often review code that they never tried to run, so provide relevant context and suggest ways to test the change. Bytes are cheap, so just write!

If your change is about fixing a bug, put that bug's number at the very beginning of the summary line in parentheses:

(bug 43546) Rephrasing unclear button labels

Since that first line is used by our Gerrit review tool to generate emails, that will make life easier to people receiving email notifications. Gerrit will also link the bug number automatically to the Bugzilla report.

Whenever you want to refer to another modification, avoid using the commit sha1 which might change until it is merged. You should refer to either the Change ID or the Change number instead. Those will be stable in time and are not altered when someone submit a new patch set on top of your commit.

Following the first summary line, add an empty line. That is how lots of programs interacting with git will actually detect the summary line.

Wrap your message body at 72 characters. This will ensure Gerrit will correctly display it and make the message suitable for display in any mail clients. Some people receiving emails notification might be using a text client such as mutt.

The full format should thus be:

(bug 1234) Summary line used as a subject usually

Rest of the message detailing your change, can be a long message if needed, for example to explain your design considerations.

Please split your paragraphs with new lines :-)

The rest is pretty much free form, you can even use ascii art since commit messages are usually displayed using a monospace font.

,         ,       /             \    ((__-^^-,-^^-__))     `-_---' `---_-'      `--|o` 'o|--' \ `  /          ): :(          :o_o: "-" ASCII Copyright (C) 2012, Free Software Foundation, Inc. Published under the GPL v2

Rendering example in the vim editor with syntax coloring:



Which, once pushed to Gerrit, will roughly look like:



And generate an IRC notification: