Gerrit/Commit message guidelines/zh

提交信息（commit message）对于您的更改来说至关重要. 它是其他人在查看您的更改时首先看到的东西.

主题
提交信息的第一行被称为主题（subject）. 主题应短于80个字符（理想情况下应在50至70个字符左右）.

A component is the general area that your commit will change.
 * 在主题一行总结您的更改的内容. 谨记，它将在代码仓库中永久保存.
 * 主题一行应使用祈使语气书写. The imperative mood sounds like you are giving instructions to someone, and might start with words like "Change", "Fix", "Add", "Remove", "Document", "Refactor", etc.
 * Good examples are "Add Badge::query to query the API", "Avoid API query in SimpleBadge", and "Support zeroes in SimpleBadge::add".
 * Bad examples would be "Added Badge::query method", "Fixed Badge::query method", "Badge can query the API", "Badge doesn't do API queries", or "Zeroes work when adding badges".
 * 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. 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.
 * Good examples: "badger: Add accessibility labels to form fields", "rdbms: Avoid infinite loop on null input", and "htmlform: Change colours to match April 2020 design".
 * Bad examples: "Implement accessibility fixes", "Don't crash", or "Make prettier with a better design".
 * Do not end the subject line with a period/full stop/dot.
 * Optionally, prefix the subject with the relevant component.

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

What is wrong with the current code? Are there other ways? If so, describe why they were not as good.
 * Why should this change be made?
 * Why should it be changed in this way?
 * Did you consider other approaches?
 * How can a reviewer test or verify that your code is working correctly?

Do:

Many editors/tools can do this automatically; 72 characters is a common width to wrap at. However, do not break URLs to make them 'fit', as this will make them un-clickable; keep them, even if they are longer. If they are not yet merged, refer to them by using their Gerrit Change-Id.
 * … separate the body from the subject with one empty line.
 * … wrap the message so that lines are a maximum of 100 characters long.
 * … refer to other commits by using a (short) Git commit hash if they are merged.

Don't:


 * … refer to other commits with a Gerrit URL.
 * Instead, use the Git commit hash. This allows easy navigation of the Git repository when offline. It also allows users of all repository viewers (Gerrit, Gitiles, Phabricator, GitHub, and local Git interfaces) to automatically navigate to other commits within the same interface. A URL can only be resolved when online and using Gerrit, which breaks the ability for people to navigate quickly.
 * … use a URL as the only explanation for a change.
 * If the change is justified by discussions elsewhere or external documentation, then briefly summarise the relevant points in the commit message.

Footer and meta-data
The most important information of the footer is the  (mandatory) and.

Format " " and " " 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.

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

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.

,,  ,  , etc.
 * 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:
 * 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  or , such as "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", etc.
 * A PHP class name, such as "Title", "User", "OutputPage", etc.; typically for classes without subdirectory in.
 * 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,  , etc.
 * "tests", "qunit", "phpunit" - for changes that only affect unit or integration test suites, or the test suite runners.

Phabricator
To reference a 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, 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  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
's  tool will automatically append the " " 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  to the last paragraph. ("Ixxx"... is the  of the other commit.) This will instruct Zuul to test the commit together with that one.

Crediting others
Add this line before the  to credit other developers working on the change. You can add more than one separated by a line break.