提交消息样式指南

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

• 一般准则
• 添加必需的代码和可选的子代码
• 添加段落
• 添加关联的 bug
• 可选择指明多个步骤
• 添加测试并自动多次运行
• 在 Change-Id 前添加缓冲区行
• 使用更改 ID 引用相关更改

通用指南

• 在首行（提交内容摘要）采用大写形式与额外的详细说明之间添加一个空行。

• 如果可能，请将第一行限制为 50 个字符，并将详细说明每行限制为 72 个字符。

  • 建议您提供详细说明，但如果第一行对更改进行了充分说明，则可以将此说明省略。
  • 50 个字符的限制并非硬性限制。尤其是在使用多个标签时，很难在 50 个字符内构成有意义的摘要。

• 请使用问题跟踪器集成，而不要在第一行中使用。

• 使用命令语气来总结提交内容。例如，“修复 file.cc 中的内存泄漏问题”，而不是“我已修正内存泄漏问题中的 file.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.

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

• https://fuchsia-review.googlesource.com/c/fuchsia/+/441776
• https://fuchsia-review.googlesource.com/c/topaz/+/114013

提交消息标记为必填项。如果提交消息的主题不包含标记，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

添加 bug

如果您希望 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 进行软过渡），请通过引用执行的上一步骤和下一步骤来指明多步骤。

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

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

[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: 行，让 deflake 自动运行。

以下示例展示了提交消息中的 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 缺少某些特定的基础架构，因此无法测试某些行为变更。如果是，请在跟踪器中创建一个关于必要基础架构支持的问题，并在更改说明中提供 bug 编号，此外还应说明如何手动测试更改，例如：

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

开发者负责对其代码进行高质量的自动化测试。审核员负责对未包含足够测试的更改提出反对意见。如需详细了解如何在 Fuchsia 项目中引入可测试和已测试的代码，请参阅 Fuchsia 可测试性评分标准。

如需了解更多提交消息选项，请参阅提交消息选项指南。

在 Change-Id 前添加了缓冲区行

当您提交更改时，系统会自动添加 Change-Id。如果您使用 git commit --amend，则可能需要在其他行和更改 ID 之间添加一个缓冲区行，以便 Gerrit 不会将更改 ID 解析为常规行，并向其添加第二个 ID。

如需了解更多具体信息，请参阅 Git 解读预告片规则。

使用 Change-Id 来引用相关更改

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

建议使用更改 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。