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. Quick summary:

Subject
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. "Change foo to bar"; not "Changes foo", "Changing foo", nor "Changed foo").
 * Since this is a title (not a paragraph) it should not end in a period/full stop, but should begin with a capital letter.
 * Optionally prefix it with the changed component.
 * It should be no more than 80 characters.

Body
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 so that lines are between 70 and 100 characters long.
 * Don't break URLs. If a URL is too long, give it its own line, but don't break or wrap it.

Cross-references

 * (For Phabricator) Add a "Bug: Txxx" keyword as the very last line (see examples below. Remember: git-review adds the Change-Id afterwards) to cross-reference a Phabricator Maniphest task/bug. This should trigger the "gerritbot" to tag the corresponding Maniphest task with . Can be used multiple times.
 * Gerrit's  tool will automatically append the "Change-Id: Ixxx" keyword to new commits.
 * (For Zuul) If you have cross-repo dependencies (your commit depends on another commit in a different repository), declare them by adding "Depends-On: Ixxx..." to the last paragraph. ("Ixxx"... is the Change-Id of the other commit.)

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 or T176. Follows-up Id5e7cbb1.

Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Patch set comments
Please do not write patch set-specific comments in the commit message (e.g. something you changed between version 1 and 2 of a patch). Instead, submit them as comments in Gerrit. Either in the diff on the specific code lines, or in the general comment area.

Subject
Bear in mind that many interfaces use the subject line to identify a commit, such as:
 * Gerrit: E-mail notifications, IRC notifications, Search results
 * Gitblit: Commit subject
 * GitHub: Commit history, Commit subject
 * ,  etc.
 * Release notes of Wikimedia deployment branches of MediaWiki
 * and much more!

In all these cases the subject is rendered as plain text. Avoid using Phabricator, Bugzilla or Git references in the subject. 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 (task references, Git hashes, and URLs all become links).

Component
You may start the subject line with a component indicating what area of the code is affected by this commit.

It should be one of the following:
 * Group of php classes (like "database", "filebackend", "installer", "jobqueue", "objectcache", "resourceloader", etc.; typically directories in ).
 * Class name (like "Title", "User", "OutputPage", etc.)
 * Module name (like "mediawiki.Title", "mediawiki.util", etc.)
 * Keyword affecting multiple areas relating to the type of change (e.g. "doc", "phpunit", "phpcs", or "build")

Auto-linking and cross-referencing
Whenever you refer to another commit, use the SHA-1 git hash of the merged commit. If the commit in still pending review, use the Gerrit Change-Id hash instead of the git hash because the hash relates to an individual patch set (which changes when rebased, thus creating a dead-end).

Phabricator
To reference a Phabricator bug or task, in the commit message mention it inline using the Txxx notation (e.g. " That fixes T169. ")

To express that a commit addresses a bug, add a  footer at the end of the commit message. (If you're amending a commit message, insert it immediately above the  line.) Bug: T169

The "gerritbot" bot will automatically update the task in Phabricator about a new change set and any significant status changes (being merged, abandoned, etc.). Additionally, it automatically tags the task with. This behaviour is only triggered when a change has the bug linked in the footer using the specified format. If the patch addresses two or more bugs, put each  etc. reference on its own line on the bottom.

Make sure there are no blank lines at the end of the commit message. This will prevent the automatic cross-referencing functionality of Gerrit Notification Bot.