Gerrit/Commit message guidelines

Commit messages play a vital role in all revision control systems, as they are usually the first thing other people will see of your commit, without the need to read the actual code.

The first line of the commit messsage — considered its "title" or "subject" — is especially important. It helps potential reviewers to see at a glance what the commit is about, and is used in many places — from e-mail notifications, bot messages on IRC, to [//gerrit.wikimedia.org/r/#/q/project:test/mediawiki+topic:bug/1236,n,z Gerrit search results], commit history on Github, and MediaWiki release notes (and many more).

It is helpful to have a concise first line of the commit. If you cannot summarise your changes in a short line, perhaps it is still too early to push it to Gerrit, or maybe it contains too many different things that should be broken up into different changesets.

Good practices
Below are listed some good practices that are used by users submitting changes to the Wikimedia Gerrit installation:
 * Subject:
 * The first line of the commit ("title" or "subject") should generally be less than 62 characters. Some people suggest less than 50 characters, but 62 is OK, too.
 * If your change resolves a Bugzilla bug, you can include its number in the first line (but it's not required). Use  or , and Gerrit will turn this into a link to the bug.
 * Body:
 * Make sure to separate the subject and the body of the message with an empty line or the body will be treated as part of the subject, which makes it pretty hard to follow the change in e-mail notifications and IRC messages.
 * Use the body of the commit message to describe your changes in detail. Explain what the change does, 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. Again, some people suggest to wrap the message at 72 characters (for use on 80 column terminals), but 70-100 characters are generally considered all right.
 * If your change resolves a Bugzilla bug, mention the ticket number in the body message, like that: .  This helps to find the bug by searching in Gerrit (example search for bug 45191). Just like above, Gerrit will turn this into a link to the bug. Don't worry if you already included the bug number in the subject; it doesn't hurt, and only helps.
 * 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. If the commit in question has not been merged yet, use the Gerrit Change-Id instead of the SHA1 as that hash may not end up becoming part of the branch and the reference would potentially be a dead end.

Example
(bug 12345) 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.

I love tootsie roll donut oat cake soufflé. Chupa chups danish carrot cake. I love chocolate candy cookie sesame snaps sesame snaps lollipop carrot cake.

Sweet roll dragée bear claw cheesecake dragée. Icing apple pie macaroon carrot cake I love I love ice cream sweet roll. Brownie powder bonbon marshmallow dessert liquorice I love tiramisu. Follows-up Id5e7cbb1.

Bug: 12345 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907