修訂版本訊息樣式指南

Git 專案提供一般指南，包括如何撰寫修訂訊息。撰寫修訂訊息時，請遵循下列準則：

一般原則

  • 在首行大寫的第一行 (修訂版本摘要) 和其他詳細說明之間新增空白行。
  • 如果可以，請將第一行長度限制在 50 個半形字元以內，且詳細說明每行 72 個半形字元。
    • 建議您提供詳細說明，但如果第 1 行有充分說明變更，則可省略。
    • 長度上限為 50 個半形字元。尤其在使用多個標記時，更難以在 50 個字元內建構有意義的摘要。
  • 使用 Issue Tracker 整合，而非第一行文字。
  • 使用命令式情緒來總結修訂版本，例如「修正 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.

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

必須提供修訂訊息標記。如果修訂訊息的主旨不含標記，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。建議您在其他行與 Change-Id 之間加入緩衝區行，以防使用 git commit --amend，因此 Gerrit 不會將變更 ID 剖析為一般行，並加入第二個 ID。

如需更多具體詳細資料，請參閱 Git 解讀預告片規則。

使用變更 ID 參照相關變更

如要在修訂訊息中參照其他 Gerrit 變更，請一律使用變更 ID。

建議使用變更 ID，原因如下：

只有在變更合併後才能知道 Git SHA，雖然指引可以在一個情況下使用 Change-Id，而在另一個情況下指示 git SHA，則偏好統一的指引。此外，您無法使用 Git SHA 參照其他存放區。

變更內容的連結由 Gerrit 指派，且不屬於存放區的永久歷史記錄。如果審查機制有所變更，變更記錄將繼續顯示在記錄中，而變更內容的數字則不會。在極少數的情況下，變更數字可能會遺失，例如因為重新建立索引的問題。

舉例來說，假設您要查看新增 RFC-0042 的變更，請使用 I32b966810d21a249647887fa45b61720ad01714c，而非 git SHA 5d40ee8c42d1b0e4d8b690786da12a0a947c1aaa 或變更內容的連結：https://fuchsia-review.googlesource.com/c/fuchsia/+/284569。