Gerrit/Commit message guidelines

From MediaWiki.org
Jump to navigation Jump to search

The commit message of your change plays an important role. It is first thing other people will see about your change.

component: 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 requests, search results, git rebase, logs, and more.

Bug: T54321

Structure[edit]

Subject[edit]

The first line of the commit message is known as the subject. The subject should be less than 80 characters long (aim for 50-70).

  • Summarize your change in the subject line. Keep in mind that this will be forever in the repository.
  • Use the imperative mood for the grammar your subject line.
    The imperative mood sounds like you're instructing someone, it can start with words like "Change ..", "Add ..", or "Fix ..". A good example is "Add Badge::query method to query the API" or "Fix Badge::query to allow zeros". A bad example is "Added Badge::query method", or "Fixed Badge::query 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).

Body[edit]

When writing the body text, think about the following questions:

  • Why should this change should be made? What is wrong with the current code?
  • Why should it be changed in this way? Are there other ways?
  • If you considered other approaches, describe why they not as good.
  • How can a reviewer confirm that your change works as intended?

Do:

  • Separate the body from the subject with one empty line.
  • Wrap the message body so that lines are less than 100 characters long. But, do not break or wrap URLs, keep them even if they are longer.
  • Format "Bug" and "Change-Id" meta-data exactly like in the examples below, and place them together at the end of the body, after one empty line.
  • Refer to other commits by using the git commit hash.

Don't:

  • Do not refer to other commits with a Gerrit URL, use the git commit hash instead. This allows easy navigation of the Git repository when offline. It also allows users all repository viewers (Gerrit, Gitiles, Phabricator, GitHub, and local Git interfaces) to automatically navigate to other commits within the same interface. A URL breaks this navigation.
  • Do not use a URL as the only explanation for a change. If there was external documentation or discussions, summarise the relevant points in the commit message.

Good Example[edit]

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

Bad Example[edit]

Improved the functionality of the code

Changed the files a.php and b.php

Bug: T42
Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907

Of note[edit]

Subject[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.

Component[edit]

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

Phabricator[edit]

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.

Cross-references[edit]

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[edit]

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

Dependencies[edit]

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]

References[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.