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.
Structure[edit | edit source]
Subject[edit | edit source]
The first line of the commit message is known as the subject. It describes the change briefly and helps reviewers to see at a glance what the commit is about.
- Use the imperative mood (e.g., "Make foo do bar" instead of "[This patch] makes foo do bar" or "[I am] changing foo to do bar").
- As being a title (not a sentence in a paragraph) it should not end in a full stop.
- Optionally prefix it with the changed component.
- It should be no more than 50 characters (must be less than 80).
Body[edit | edit source]
Use the body of the commit message to describe your change in detail.
- Separate the body from the subject with an empty line.
- Give an overview of why you're committing this change.
- What the commit changes.
- Any new design choices made.
- Areas to focus on for recommendations or to verify correct implementation.
- Any research you might have done.
- Bytes are cheap, so just write!
- Try to make your commit message understandable without external resources (e.g., instead of just giving a URL to a mailing list archive, summarize the relevant points of the discussion).
- Wrap the body of the message between 70 and 100 characters.
- Use the "Bug:" keyword to cross-reference a Bugzilla ticket.
- The "Change-Id" keyword will automatically be added to new commits by Gerrit.
Example[edit | edit source]
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
Of note[edit | edit source]
Patch set comments[edit | edit source]
Please do not add patch set-specific comments to the commit message body. Instead, enter patch set-specific comments as Gerrit patch set comments on the specific code lines or in the general patch set comment area.
Subject[edit | edit source]
Bear in mind that many interfaces use the subject to identify a commit, such as:
- Gerrit: E-mail notifications, IRC notifications, Search results
- Gitblit: Commit subject
- GitHub: Commit history, Commit subject
git log --onelineetc.
- Release notes of Wikimedia deployment branches of MediaWiki
- 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).
[edit | edit source]
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 SHA1 reference would potentially be a dead end).
To reference a bug (from our Bugzilla installation) in the commit message mention it inline using the
bug keyword (lowercase) followed by one space and only the bug number (e.g. " ")
To express that a commit addresses a bug, add a line like the following directly above the
Change-Id line in the footer; the colon ":" is mandatory, and there must be no blank lines separating them:
A bot will automatically notify Bugzilla about a new change set and any significant status changes (being merged, abandoned, etc.). Additionally, the bug's status gets set to
PATCH_TO_REVIEW. This behaviour is only triggered when a change has the bug linked in the footer using the specified format.