Git commit“約定式提交”規範

語言: CN / TW / HK
時間 2022-05-14 00:24:56
主題:

版權宣告：本文來源於網友收集或網友提供，僅供學習交流之用，如果有侵權，請轉告版主或者留言，本公眾號立即刪除。

概述

約定式提交規範是一種基於提交資訊的輕量級約定。它提供了一組簡單規則來建立清晰的提交歷史；這更有利於編寫自動化工具。通過在提交資訊中描述功能、修復和破壞性變更， 使這種慣例與 SemVer 相互對應。

提交說明的結構如下所示：

原文：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

譯文：

<型別>[可選 範圍]: <描述>

[可選 正文]

[可選 腳註]

提交說明包含了下面的結構化元素，以向類庫使用者表明其意圖：

  1. fix: 型別 為  fix 的提交表示在程式碼庫中修復了一個 bug（這和語義化版本中的  PATCH 相對應）。

  2. feat: 型別 為  feat 的提交表示在程式碼庫中新增了一個功能（這和語義化版本中的  MINOR 相對應）。

  3. BREAKING CHANGE: 在腳註中包含  BREAKING CHANGE: 或 <型別>(範圍) 後面有一個  ! 的提交，表示引入了破壞性 API 變更（這和語義化版本中的  MAJOR 相對應）。破壞性變更可以是任意  型別 提交的一部分。

  4. 除 fix: 和  feat: 之外，也可以使用其它提交  型別 ，例如 @commitlint/config-conventional（基於 Angular 約定）中推薦的  build: 、 chore: 、  ci: 、 docs: 、 style: 、 refactor: 、 perf: 、 test: ，等等。

  5. 腳註中除了 BREAKING CHANGE: <description> ，其它條目應該採用類似 git trailer format 這樣的慣例。

其它提交型別在約定式提交規範中並沒有強制限制，並且在語義化版本中沒有隱式影響（除非它們包含 BREAKING CHANGE）。 可以為提交型別新增一個圍在圓括號內的範圍，以為其提供額外的上下文資訊。例如 feat(parser): adds ability to parse arrays. 。

示例

包含了描述並且腳註中有破壞性變更的提交說明

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

包含了 ! 字元以提醒注意破壞性變更的提交說明 

feat!: send an email to the customer when a product is shipped

包含了範圍和破壞性變更 ! 的提交說明 

feat(api)!: send an email to the customer when a product is shipped

包含了 ! 和 BREAKING CHANGE 腳註的提交說明 

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

不包含正文的提交說明

docs: correct spelling of CHANGELOG

包含範圍的提交說明

feat(lang): add polish language

包含多行正文和多行腳註的提交說明

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

約定式提交規範

本文中的關鍵詞 “必須（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“應當（SHALL）”、“不應當（SHALL NOT）”、“應該（SHOULD）”、“不應該（SHOULD NOT）”、“推薦（RECOMMENDED）”、“可以（MAY）” 和 “可選（OPTIONAL）” ，其相關解釋參考 RFC 2119 。

  1. 每個提交都 必須 使用型別欄位字首，它由一個名詞構成，諸如  feat 或  fix ， 其後接 可選的 範圍欄位， 可選的 ! ，以及 必要的 冒號（英文半形）和空格。

  2. 當一個提交為應用或類庫實現了新功能時， 必須 使用  feat 型別。

  3. 當一個提交為應用修復了 bug 時， 必須 使用  fix 型別。

  4. 範圍欄位 可以 跟隨在型別欄位後面。範圍 必須 是一個描述某部分程式碼的名詞，並用圓括號包圍，例如：  fix(parser):

  5. 描述欄位 必須 直接跟在 <型別>(範圍) 字首的冒號和空格之後。描述指的是對程式碼變更的簡短總結，例如：  fix: array parsing issue when multiple spaces were contained in string 。

  6. 在簡短描述之後， 可以 編寫較長的提交正文，為程式碼變更提供額外的上下文資訊。正文 必須 起始於描述欄位結束的一個空行後。

  7. 提交的正文內容自由編寫，並 可以 使用空行分隔不同段落。

  8. 在正文結束的一個空行之後， 可以 編寫一行或多行腳註。每行腳註都 必須 包含 一個令牌（token），後面緊跟  :<space> 或  <space># 作為分隔符，後面再緊跟令牌的值（受 git trailer convention 啟發）。

  9. 腳註的令牌 必須 使用  - 作為連字元，比如  Acked-by (這樣有助於 區分腳註和多行正文)。有一種例外情況就是  BREAKING CHANGE ，它 可以 被認為是一個令牌。

  10. 腳註的值 可以 包含空格和換行，值的解析過程 必須 直到下一個腳註的令牌/分隔符出現為止。

  11. 破壞性變更 必須 在提交資訊中標記出來，要麼在 <型別>(範圍) 字首中標記，要麼作為腳註的一項。

  12. 包含在腳註中時，破壞性變更 必須 包含大寫的文字  BREAKING CHANGE ，後面緊跟著冒號、空格，然後是描述，例如：  BREAKING CHANGE: environment variables now take precedence over config files 。

  13. 包含在 <型別>(範圍) 字首時，破壞性變更 必須 通過把  ! 直接放在  : 前面標記出來。如果使用了  ! ，那麼腳註中 可以 不寫  BREAKING CHANGE: ， 同時提交資訊的描述中 應該 用來描述破壞性變更。

  14. 在提交說明中， 可以 使用  feat 和  fix 之外的型別，比如： docs: updated ref docs. 。

  15. 工具的實現必須 不區分 大小寫地解析構成約定式提交的資訊單元，只有  BREAKING CHANGE 必須 是大寫的。

  16. BREAKING-CHANGE 作為腳註的令牌時 必須 是 BREAKING CHANGE 的同義詞。

為什麼使用約定式提交

  • 自動化生成 CHANGELOG。

  • 基於提交的型別，自動決定語義化的版本變更。

  • 向同事、公眾與其他利益關係者傳達變化的性質。

  • 觸發構建和部署流程。

  • 讓人們探索一個更加結構化的提交歷史，以便降低對你的專案做出貢獻的難度。

FAQ

在初始開發階段我該如何處理提交說明？

我們建議你按照假設你已釋出了產品那樣來處理。因為通常總 有人 使用你的軟體，即便那是你軟體開發的同事們。他們會希望知道諸如修復了什麼、哪裡不相容等資訊。

提交標題中的型別是大寫還是小寫?

大小寫都可以，但最好是一致的。

如果提交符合多種型別我該如何操作？

回退並儘可能建立多次提交。約定式提交的好處之一是能夠促使我們做出更有組織的提交和 PR。

這不會阻礙快速開發和迭代嗎？

它阻礙的是以雜亂無章的方式快速前進。它助你能在橫跨多個專案以及和多個貢獻者協作時長期地快速演進。

約定式提交會讓開發者受限於提交的型別嗎（因為他們會想著已提供的型別）？

約定式提交鼓勵我們更多地使用某些型別的提交，比如 fixes 。除此之外，約定式提交的靈活性也允許你的團隊使用自己的型別，並隨著時間的推移更改這些型別。

這和 SemVer 有什麼關聯呢？

fix 型別提交應當對應到  PATCH 版本。 feat 型別提交應該對應到  MINOR 版本。帶有  BREAKING CHANGE 的提交不管型別如何，都應該對應到  MAJOR 版本。

我對約定式提交做了形如 @jameswomack/conventional-commit-spec 的擴充套件，該如何版本化管理這些擴充套件呢？

我們推薦使用 SemVer 來發布你對於這個規範的擴充套件（並鼓勵你建立這些擴充套件！）

如果我不小心使用了錯誤的提交型別，該怎麼辦呢？

當你使用了在規範中但錯誤的型別時，例如將 feat 寫成了  fix

在合併或釋出這個錯誤之前，我們建議使用 git rebase -i 來編輯提交歷史。而在釋出之後，根據你使用的工具和流程不同，會有不同的清理方案。

當使用了 不在 規範中的型別時，例如將  feat 寫成了  feet

在最壞的場景下，即便提交沒有滿足約定式提交的規範，也不會是世界末日。這隻意味著這個提交會被基於規範的工具錯過而已。

所有的貢獻者都需要使用約定式提交規範嗎？

並不！如果你使用基於 squash 的 Git 工作流，主管維護者可以在合併時清理提交資訊——這不會對普通提交者產生額外的負擔。有種常見的工作流是讓 git 系統自動從 pull request 中 squash 出提交，並向主管維護者提供一份表單，用以在合併時輸入合適的 git 提交資訊。

約定式提交規範中如何處理還原（revert）提交?

還原提交（Reverting）會比較複雜：你還原的是多個提交嗎？如果你還原了一個功能模組，下次釋出的應該是補丁嗎？

約定式提交不能明確的定義還原行為。所以我們把這個問題留給工具開發者， 基於 型別 和  腳註 的靈活性來開發他們自己的還原處理邏輯。

一種建議是使用 revert 型別，和一個指向被還原提交摘要的腳註： 

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868
「」