Gerrit/Commit message guidelines

Jump to navigation Jump to search

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

Short subject line

More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review e-mails, search results, git-rebase, and more.

Bug: T54321



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).
  • Optionally prefix the subject with the relevant component (the general area of code being modified).


  • 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.


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

Of note[edit]


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.


You may optionally 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 includes/ or includes/libs/).
  • Class name (like "Title", "User", "OutputPage", etc.; typically classes without subdirectory in includes/)
  • ResourceLoader module name (like "mediawiki.Title", "mediawiki.util", etc.)
  • Keyword affecting multiple areas relating to the type of change (e.g. "build", "phpunit", or "phpcs")


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 Bug: Txxx in the footer at the end of the commit message.[1] (If you're amending a commit message, insert it immediately above the Change-Id: 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 Bug: T12345 reference on its own line at the bottom.


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


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


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.

Further reading[edit]


  1. As with all headers/footers: Write the name with words individually capitalized, with hyphens between (e.g. Hypothetical-Header-Or-Footer). Follow the name with a colon (":"), then one space. Similar to the Git commit, HTTP and E-mail headers, adding extra blank lines above the footer would cut off the footer and wrongly include the former part in the body.