For repositories that have a .gitmessage file in the repo (e.g. mediawiki/core), you can encourage yourself to good commit hygiene, by running the following command in your checked out repo
git config commit.template .gitmessage
If you like it, you are encouraged to add it to more repos
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
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).
.
).When writing the body text, think about the following questions:
Recommended:
I83f83377f2
or Git commit hash like 51e3fb9a71
. If the related change is not yet merged, always use the Gerrit Change-Id as the Git commit hash will change once it is merged, which would lead then become a dead-end.Not recommended:
I83f83377f2
or Git commit hash like 51e3fb9a71
. This kind of hash is automatically converted to a link when viewing the change in Gerrit, Gitiles, and other repository browsers. It also allows for easy navigation in the Git repository during development such as via git show
or inside text editors.The most important information of the footer is the Change-Id
(mandatory) and Bug
.
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.
Find more information on individual meta-data fields below.
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
Improved the code by fixing a bug. Changed the files a.php and b.php Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
If the repository you are contributing to has a
.gitmessage
file (
example), use the following command to get a template to guide you in writing a commit message:
git config commit.template .gitmessage
Most programs we use that display Git commit, render the subject line as plain text. This means URLs do not work, and selecting/copying of text often is not possible. Therefore, do not mention Phabricator tasks, Git commits, or urls inside the subject line. Instead, mention those in the body text, or footer meta-data. That way, they can be universally selected, copied, or clicked.
git shortlog
, git log --oneline
, git rebase -i
, git show
, etc.You may start the subject line with a component, which will indicate what area of the project is changed by your commit.
It should be one of the following:
includes/
or includes/libs
, containing the PHP classes most relevant to the commit. Examples include installer
, jobqueue
, objectcache
, resourceloader
, rdbms
.includes/
nor includes/libs
. Examples include EntryPointEnvironment
, MainConfigNames
, PHPVersionCheck
.mediawiki.Title
, mediawiki.util
.package.json
, .travis.yml
, etc.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.[2] (If you're amending a commit message, insert it immediately above the Change-Id:
line, without an empty line between them. Remember to follow the overall structure rules and separate the body from the subject with one empty 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.
Bug: T299087 Bug: T299088
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.
Depends-On: Ixxx
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.
To provide additional guidance to developers, you can indicate the inverse relationship using Needed-By: Iyyy...
in last paragraph of the commit message in the other repository. ("Iyyy"... is the Change-Id
of your commit.) Note that Zuul does not react to this, it is just for the benefit of human readers. Also, Gerrit will automatically add backlinks based on the presence of Depends-On
, regardless of any Needed-By
.
Co-Authored-by: gerrit_username <gerrit_user_email@example.com>
Add this line before the Change-Id
to credit other developers working on the change. You can add more than one separated by a line break.
Note that unlike other words in commit message footers, the word by
is not capitalised; it's Co-Authored-by
, not Co-Authored-By
.
Hypothetical-Header-Or-Footer
). Follow the name with a colon (":"), then one space. Similar to the Git commit, HTTP and Email headers, adding extra blank lines above the footer would cut off the footer and wrongly include the former part in the body.RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4