Gerrit/提交消息指引
此页面记载MediaWiki的开发指引,由开发人员随着时间推移达成共识,精心制作而来(或有些时候由开发人员的领导公告而来) |
提交信息(commit message)对于您的更改来说至关重要。 它是其他人在查看您的更改时首先看到的东西。
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
结构
主题
提交信息的第一行被称为主题(subject)。 主题应短于80个字符(理想情况下应在50至70个字符左右)。
- 在主题一行总结您的更改的内容。 谨记,它将在代码仓库中永久保存。
- Optionally, prefix the subject with the relevant component. A component is the general area that your commit will change.
- 主题一行应使用祈使语气书写。 Avoid stating a fact, like "Badge hides zero" or "Zero in badges", which is ambigious and does not describe a change (good or bad? before or after?). Consider instead "Hide zeroes in badges", "Show zeroes in badges", or "Badge: Restore display of zero".
The imperative mood is when you give instructions to someone, and often starts with words like "Change", "Fix", "Add", "Remove", "Document", "Refactor", etc. - Your subject line should be short, clearly state what your commit is changing.
It should not be possible to use the same subject line for two commits that do different things. Consider "Fix FooBar docs to use @chainable" instead of "Fix a function doc". People will read your subject line out of context, as it passes by in change feeds, code review emails, git-blame logs, release notes, deployment changelog, etc. A good subject line helps decide quickly whether this commit among many will be relevant to a given interest or concern. - Do not end the subject line with a period/full stop/dot (
.
).
Good examples are: | Bad examples would be: |
---|---|
|
|
Body
When writing the body text, think about the following questions:
- Why should this change be made? What is wrong with the current code?
- Why should it be changed in this way? Are there other ways?
- Did you consider other approaches? If so, describe why they were not as good.
- How can a reviewer test or verify that your code is working correctly?
Recommended:
- Separate the body from the subject with one empty line.
- Wrap the message so that lines are a maximum of 100 characters long. Many editors/tools can do this automatically; 72 characters is a common width to wrap at.[1] However, do not break URLs to make them 'fit', as this will make them un-clickable; keep them, even if they are longer.
- Refer to other commits by using a (short) Gerrit Change-Id like
I83f83377f2
or Git commit hash like51e3fb9a71
. 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:
- Don't refer to other commits with a URL or change number.
- Instead, use the Gerrit Change-Id like
I83f83377f2
or Git commit hash like51e3fb9a71
. 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 viagit show
or inside text editors. - On the other hand, a URL can only be resolved in a web browser and goes to a fixed location, which breaks code review workflows and departs from local context. For example, inside a Git browser the hash allows you to quickly go from one commit to a related one in the same tool, instead of being sent to Gerrit. The hashes can also be searched for in Gerrit to automatically find commits that refer to it.
- Another issue is that change numbers can ambiguous or become automatically linked to a different commit than you intend. This is because commit hashes are sometimes numbers only, e.g. commit 665661 is different than change 665661.
- Instead, use the Gerrit Change-Id like
- Don't use only a URL as the explanation for a change.
- If the change is justified by a discussion elsewhere or some external documentation, try to summarise the key point(s) in your commit message and refer to the URL as well.
Footer and meta-data
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.
Examples
Good 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
Bad example
Improved the code by fixing a bug. Changed the files a.php and b.php Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
Additional information
.gitmessage
file (example), use the following command to get a template to guide you in writing a commit message: git config commit.template=.gitmessage
Subject
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.
- Gerrit uses the subject in: email notifications, IRC notifications, search results.
- GitHub uses the subject in: commit history, commit subject.
- The Git CLI uses the subject in:
git shortlog
,git log --oneline
,git rebase -i
,git show
, etc. - Release notes of Wikimedia deployment branches of MediaWiki
- and much more!
Component
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:
- A directory of PHP classes under
includes/
orincludes/libs
, such as "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", etc. - A PHP class name, such as "Title", "User", "OutputPage", etc.; typically for classes without subdirectory in
includes/
. - ResourceLoader module name (like "mediawiki.Title", "mediawiki.util", etc.).
- Generic keyword affecting multiple areas relating to the type of change, such as:
- "build" - for changes to files relating to the development workflow, such as updates to
package.json
,.travis.yml
, etc. - "tests" or "test" (depending on directory name) - for changes that only affect QUnit or PHPUnit test suites, or the test suite runners.
- "build" - for changes to files relating to the development workflow, such as updates to
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 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
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 git-review
tool will automatically append the "Change-Id: Ixxx
" keyword to new commits.
Dependencies
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
.
Crediting others
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.
by
is not capitalised; it's Co-Authored-by
, not Co-Authored-By
.Further reading
- 手册:代码编写约定
- Commit-消息-验证器
- Gerrit Commit Guidelines
- Node.js Commit Guidelines
- Git Core Commit Guidelines
- jQuery Commit Guidelines
- Erlang Commit Guidelines
- A Note About Git Commit Messages - by Tim Pope
- How to Write a Git Commit Message - by Chris Beams
- Gerrit integrations with the Puppet Catalogue Compiler
References
- ↑ This is a legacy from times when lines were provided on punched cards. Columns 1 to 72 where used for the statement and columns 73 to 80 for short comments. Size 72 is reasonable enough to understand the code at first glance.
- ↑
As with all headers/footers, write the name with words individually capitalised, 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 Email headers, adding extra blank lines above the footer would cut off the footer and wrongly include the former part in the body.