Gerrit/Commit message guidelines

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

Subject
The first line of the commit message is known as the subject. It should be less than 80 characters long (aim for 50-70).
 * Write the subject line in the imperative mood (as if you're instructing someone). Start with "Change", "Add", "Fix", etc. not "Added" or "Fixes". For example "Add api-edit method".
 * Do not end the subject with a period (full stop).
 * Prefix the subject with the relevant component (the general area of code being modified).

Body

 * Separate the body from the subject with an empty line.
 * Think about the following questions:
 * Why should this change should be made? What is wrong with the current code?'
 * Why should it be done in this particular way?
 * Did you try a different way before? Describe alternate approaches you considered.
 * Can a reviewer confirm that it works as intended?
 * Avoid URLs in commit messages.
 * Use git hashes instead of URLs to refer to other changes.
 * If there was external documentation or discussions, also summarise the relevant points.
 * Wrap the message body so that lines are less than 100 characters long. If a URL is too long, give it its own line, but don't break or wrap it.
 * Be careful to keep the Bug and Change-id lines like they are formatted in the example.

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 T44834 or T176. Follow-up to Id5e7cbb1.

Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Subject
Bear in mind that many interfaces use the subject line to identify a commit. In all the below use cases, the subject is rendered as plain text. Avoid using Phabricator tasks, Git references, or urls in the subject line. Instead, mention those in the body or footer.
 * Diffusion: Commit subject
 * Gerrit: E-mail notifications, IRC notifications, Search results
 * GitHub: Commit history, Commit subject
 * Release notes of Wikimedia deployment branches of MediaWiki
 * and much more!
 * and much more!

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")

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

To express that a commit resolves (even partially) or is specially relevant to a bug, add  in the footer at the end of the commit message. (If you're amending a commit message, insert it immediately above the  line.) Bug: T169

A bot will automatically leave a comment on the Phabricator task about any significant events (being merged, abandoned, etc.). If a patch resolves two or more bugs, put each   reference on its own line at the bottom.

Cross-references
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).

Change-Id
Gerrit's  tool will automatically append the "Change-Id: Ixxx" keyword to new commits.

Dependencies
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.) This will instruct Zuul to test the commit together with that one.