Gerrit/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 toola as a summary of your commit message. You will thus have a first line which is meaningful and short 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. Bytes are cheap, so just write!

If your change is about fixing a bug, you will want to use that bug number at the very beginning of the summary line in parentheses. Since that first line is used by our Gerrit review tool to generate emails, that will make life easier to people receiving email notifications.

Whenever you want to refer to another modification, avoid using the commit sha1 which might change until it is merged. You will usually want to refers 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, you want to add an empty line. That is how lots of programs interacting with git will actually detect the summary line.

Finally, you will want to 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 you new lines :-)

Rest is pretty much free form, you can even use ascii art since commit
message 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 looks like:

And generates an IRC notification:

See other explanations at:

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

http://en.wikibooks.org/wiki/Git/Introduction#Good_commit_messages