Gerrit/Commit message guidelines

The commit message plays an important role in revision control systems. They are the first thing other people will see of your commit.

Conventions

 * 1) The first line of the commit message is known as the subject and describes the change briefly (optionally prefix it with the changed component). It should be no more than 50 characters (must be less than 62).
 * 2) Keep the second line empty. This separates the subject from the body. Without this the following lines will be interpreted as part of the subject.
 * 3) Use the body of the commit message to describe your change in detail. Explain what the commit changes, your design choice, possible culprits to look at, and any research you might have done. Bytes are cheap, so just write! Wrap the body of the message between 70 and 100 characters.

Subject
The first line of the commit message (the "subject") is especially important. It helps reviewers to see at a glance what the commit is about.

Phrase your subject in imperative mood. For example "make foo do bar" instead of "[This patch] makes foo do bar" or "[I am] changing foo to do bar".

If you are unable to summarise your change in a short line, perhaps it is too early to push it to Gerrit, or maybe it contains too many different things that should be broken up into different commits.

Many interfaces use the subject to identify a commit, such as:
 * E-mail notifications from Gerrit
 * IRC notifications from gerrit-wm
 * Search results in Gerrit
 * Commit history at GitHub
 * Commit subject at GitHub
 * ,  etc.
 * Release notes of Wikimedia deployment branches of MediaWiki
 * and much more
 * and much more

In all these cases the subject is rendered as plain text. Avoid using bugzilla or git references in the subject as they have no meaning in plain text. Instead mention them in the body text and/or as key-value pairs in the footer. When someone views the change in Gerrit this data is parsed (bug references, git hashes, urls all become linkified).

As being a title (not a sentence in a paragraph) it should not end in a full stop. Though one can argue about the semantics of it being a sentence or a title, consistency is important and we don't end in a full stop.

Body
Try to make your commit message understandable without external resources. Instead of just giving a URL to a mailing list archive, summarize the relevant points of the discussion.

Whenever you refer to another commit, use either the SHA-1 of the merged commit, or the Gerrit Change-Id of the changeset in Gerrit (avoid using Gerrit or Gitweb urls). If the commit in question has not been merged yet, use the Gerrit Change-Id instead of the SHA1 because the SHA1 changes every patch set (the SH1 reference would potentially be a dead end).

Referencing Bugs
To reference a bug (from our bugzilla) in the commit message, use  or   followed by an optional colon, followed by at least one whitespace, followed by an optional hash mark, followed by the bug number.

So for example, all of the following link to bug 44441 get autolinked in Gerrit when showing commit messages.
 * 
 * 
 * 

Addressing bugs vs. only mentioning them
To express that a commit tries to address a bug, add a line Bug: directly above the  line, see example below. For such bug references, Gerrit automatically adds Bugzilla comments about merging, abandoning, etc. to the corresponding bugs that link back to Gerrit.

Bug references at other places in the commit message get autolinked within Gerrit, but will not be added as comments in Bugzilla. In that way you can distinguish between addressing a bug (Bug 12345 in the example below), or just mentioning it (Bug 44441 in the example below).

Example
jquery.badge: Add ability to display the number zero

Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas. Does not yet address bug 44441. Follows-up Id5e7cbb1.

Bug: 12345 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907