修訂版本訊息樣式指南

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 可測試性評分標準。

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

在變更 ID 前加入緩衝區行

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

詳情請參閱 Git 解譯預告規則。

使用變更 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。