提交消息样式指南

Git 项目提供了一般准则，包括如何编写提交消息。编写提交消息时，请遵循以下准则：

通用指南

  • 在大写的第一行（提交摘要）和其他详细说明之间添加一个空行。
  • 如果可能，请将第一行的长度限制为 50 个字符，将详细说明的长度限制为每行 72 个字符。
    • 我们建议您提供详细说明，但如果第一行能够很好地说明更改，则可以省略详细说明。
    • 50 个字符的限制并非硬性限制。特别是在使用多个标记时，可能很难用 50 个字符来组织有意义的摘要。
  • 请使用问题跟踪器集成，但不要使用第一行。
  • 使用命令式语气总结提交内容，例如“修复 file.cc 中的内存泄漏”，而不是“我修复了文件.cc 中的内存泄漏问题”。
  • 请勿引用相对时间点、私有网址、个人、API 私钥、密码、用户名等。

添加必需的标记

第一行中必需的 [tag] 有助于提交的读取者了解更改所涉及的主题。格式就是方括号之间的关键字，例如 [docs]。关键字没有特定含义，但应该有助于读者轻松识别主题。也可以使用更具体的标记或多个标记来指定更精细的主题，例如 [docs][fidl]。以下示例展示了提交消息主题中的必需标记：

[parent][component] Update component in Fuchsia

Write the details of a commit message here.

Bug: <issue-tracker-ID>

Test: Added test X.

您可以查看修改过的文件的提交历史记录，以检查之前使用的标记。请参阅以下示例：

提交消息标记是必填项。如果提交消息的主题不包含标记，Gerrit 会使用 Needs Label: Commit-Message-has-tags 标记您的更改。

添加段落

标题行下方的段落可更详细地描述这项更改。 确保清楚说明更改的原因和意图：例如：

[docs] Adding Fuchsia Commit message style guide

This change centralizes all commit message style guide into one style
guide. It also removes duplicate content from existing pages and points
to the new style guide instead.

Change-Id: I307e5b24df4273661d22c52c81038de50600c76c

添加错误

如果您希望 Fuchsia Gerrit 知道此变更与什么问题相关，则需要添加 Bug: <issue-tracker-ID> 行。如需将多个问题与一项变更相关联，请单独列出每个 bug。例如：

[parent][component] Update component in Fuchsia

Write the details of a commit message here.

Bug: 82657
Bug: 82658

Test: Added test X.

Bug: 和 Fixed: 之间的区别在于，Fixed: 会在您提交更改后自动为您关闭问题，而 Bug: 仅在提交后才评论您的问题。如果您的问题附加了多项更改，请在最终更改之前对全部更改使用 Bug: 标记。请对最终更改使用 Fixed:，以便关闭问题。

指明多个步骤

在执行需要跨不同代码库执行多个步骤的更改时（例如，到在一个代码库中定义的软转换 API，在其他代码库中使用的 API），请引用上一步和已执行的步骤来指示多个步骤。

这样，审核者和查看日志的人员就可以了解并浏览更改的总体情况。建议尽可能在每个提交日志中提供完成迁移的所有步骤（但在某些情况下可能不切实际）。

下面是一个包含多个步骤的提交消息示例：

[fidl][go] Support for flexible enums (1/3)

Step 1 of 3. Adds support for flexible enums to fidlgen_go:

* For all enums, emit `IsUnknown()` method indicating whether the
  value is unknown (or known). While relevant only for flexible enums,
  it is possible to construct unknown strict enums using type casts.
* Emit an internal method `I_EnumIsStrict` indicating whether the enum
  is strict or flexible. This method is read by the runtime, when
  creating enum marshaler.
* For flexible enums, we generate a default unknown placeholder

Step 2: I1102f244aa5ab4545fab21218c1da90be08604ec
Step 3: If0a047a4db804a183e984676217b31e17b4af0ea

Test: fx test fidl_go_conformance at If0a047a4db804a183e984676217b31e17b4af0ea

Change-Id: Id71eb879e4d7dfabe228cc7b4e2fedb7f52db7b7

添加测试并乘以一行

Test: 行是指明要运行的测试类型，以确保您的更改能够正常运行的必要条件。您可以在此行中添加多个不同的测试，例如 fx test setui_service_tests, setui_client_interface_test。您还可以在下面添加所添加测试的说明。如果您没有添加或修改测试，则可以指定 None:，并说明不需要测试它的原因，例如 None: documentation change only。

如果您添加了新测试，则可以向要运行多次的测试添加 Multiply: 行，从而自动消除运行稳定性。

以下示例显示了提交消息中的 Test: 和 Multiply:：

[SetUI] Correct internal items' visibility Part II

This CL marks some internal items with pub(crate), pub(super) or leaves
as private. Related CL: fxr/535942

Bug: 72941
Test: fx test -o setui_service_tests setui_client_interface_test
sample-setui-config-test setting-service-config-test
Multiply: setui_service_tests
Multiply: setui_client_interface_test

Change-Id: I67e061edee1e81a6875bf26b752ba5687c4ced71

如果测试说明很复杂，请创建一个问题，并在更改说明中提供该问题的链接。如果更改不希望更改行为，请在提交消息中指明这一事实。

在某些情况下，由于 Fuchsia 缺少一些特定的基础架构，因此无法测试某些行为变更。如果是这样，请在跟踪器中创建有关必要基础架构支持的问题，并在更改说明中提供错误编号，以及说明如何手动测试更改，例如：

Test: Manually tested that [...]. Automated testing needs US-XXXX.

开发者负责对其代码进行高质量的自动测试。审核人员应负责驳回包含足够测试的更改。如需详细了解如何在 Fuchsia 项目中引入可测试和测试的代码，请参阅 Fuchsia 可测试性评分准则。

在 Change-Id 前添加缓冲区行

当您提交更改时，系统会自动添加 Change-Id。您可能需要在其他行与 Change-Id 之间添加缓冲区行，如果您使用的是 git commit --amend，这样 Gerrit 就不会将 Change-Id 解析为常规行，也不会向其中添加第二个 ID。

如需了解更多详细信息，请参阅 Git 解释预告片规则。

使用 Change-Id 引用相关更改

如需在提交消息中引用其他 Gerrit 更改，请始终使用 Change-Id。

最好使用 Change-Id，因为：

git SHA 只有在合并变更后才会知道，在一种情况下，指导是使用 Change-Id，在另一种情况下使用 git SHA，所以倾向于使用统一指导。此外，您无法使用 Git SHA 引用其他代码库。

指向更改的链接由 Gerrit 分配，不属于代码库的持久性历史记录。如果审核机制发生变化，Change-Id 将继续出现在记录的历史记录中，而变更的编号不会。在极少数情况下，变更编号可能会丢失，例如，由于重新编入索引的问题。

例如，如需引用添加了 RFC-0042 的变更，请使用 I32b966810d21a249647887fa45b61720ad01714c，而不是 git SHA 5d40ee8c42d1b0e4d8b690786da12a0a947c1aaa 或指向该变更的链接：https://fuchsia-review.googlesource.com/c/fuchsia/+/284569。