修訂版本訊息樣式指南

Git 專案提供一般規範，包括如何撰寫提交訊息。撰寫提交訊息時，請遵循以下規範：

一般原則

  • 在第一行 (版本提交摘要) 和額外的詳細說明之間加入空白行。

  • 盡可能將第一行限制在 50 個半形字元以內，並將詳細說明限制在每行 72 個半形字元以內。

    • 建議提供詳細說明，但如果第一行已充分說明變更內容，則可省略。
    • 50 個字元並非硬性限制。尤其是使用多個標記時，很難在 50 個字元內編寫有意義的摘要。

  • 請使用問題追蹤工具整合，但不要在第一行使用。

  • 使用命令式語氣來總結提交內容。例如「Fix memory leak in file.cc」，而不是「I fixed a memory leak the 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.

您可以查看已編輯檔案的提交記錄，檢查先前使用的標記。請參閱以下範例：

必須提供提交訊息標記。如果提交訊息的主旨未包含標記，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> 行。如要將多個問題與變更相關聯，請在不同行中列出每個錯誤。例如：

[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 缺少某些特定基礎架構，因此無法測試特定行為變更。如果是這樣，請在追蹤器中建立有關必要基礎架構支援的問題，並在變更說明中提供錯誤編號，以及說明如何手動測試變更，例如：

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

開發人員負責為程式碼進行高品質的自動化測試。審查人員有責任拒絕未納入足夠測試的變更。如要進一步瞭解如何在 Fuchsia 專案中引入可測試且已測試的程式碼，請參閱 Fuchsia 可測試性評分標準。

如需更多修訂訊息選項，請參閱修訂訊息選項指南。

在 Change-Id 前方新增緩衝區行

提交變更時，系統會自動新增變更 ID。如果您使用 git commit --amend，建議您在其他行和 Change-Id 之間加入緩衝區行，以免 Gerrit 將 Change-Id 解析為一般行，並在該行中加入第二個 ID。

如需更多詳細資訊，請參閱「Git 解讀尾隨規則」。

使用 Change-Id 參照相關變更

如要在提交訊息中參照其他 Gerrit 變更，請務必使用 Change-Id。

建議使用 Change-Id，因為：

只有在變更合併後，才會知道 git SHA，雖然我們可以提供指引，在某種情況下使用 Change-Id，在另一種情況下使用 git SHA，但建議您採用統一的指導方針。此外，您也無法使用 git SHA 參照其他存放區。

變更連結是由 Gerrit 指派，並非存放區的持續性記錄的一部分。如果審查機制有所變更，變更 ID 將繼續保留在記錄的歷史記錄中，但變更的編號則不會。在極少數情況下，變更編號也可能會遺失，例如因為重新建立索引的問題。

舉例來說，如要參照新增 RFC-0042 的變更，請使用 I32b966810d21a249647887fa45b61720ad01714c，而非 git SHA 5d40ee8c42d1b0e4d8b690786da12a0a947c1aaa 或變更的連結 https://fuchsia-review.googlesource.com/c/fuchsia/+/284569。