格式化 Git commit message - Angular format

工作上大家經常會使用到版本管理軟體，大多數使用的都是 git

但是基本上 git 的 commit message 原則上沒有任何規範，想寫什麼都可以～

自己寫的話，自有風格或是自己看得懂就好也沒差，但是在團隊合作的專案上，各自為政的風格就很危險。 因為會導致版本管理上，或是後續維護上造成一些困擾。

所以就有很多人發展出了一些不成文的規範或是規定。 這邊就來介紹一個這幾年來用的一個不錯的規範： Angular format

以目的來說，git log / commit message 的目的在於

• 基本目的
  • 紀錄自己做了什麼事
  • 讓別人知道自己做了什麼事
• 進階目的
  • 紀錄專案的開發進度
  • 快速產出 Product release note / change log

這邊給一個常見的錯誤範例

這邊可以看到過於混亂，隨性的 commit message 不僅看不出開發進展，也看不出到底具體做了什麼東西

有規範的 commit message 就會看起來像這樣

不僅每一筆都相對有結構的說明屬性（修Bug、加功能），影響區塊，精簡的修改說明 並且只要有結構，格式的東西，就能夠自動化的產生 Release note

Angular format

這個格式基本上分成3個部分

• Header：標頭（必填）
• Body：內容（選填）
• Footer：頁腳（選填）

注意！ 標頭與內容中間一定要隔兩行（也就是中間要有一行完全空白） 這樣才能確保「內容」的部分在 git log 不會跟「標頭」黏再一起 （只隔一行的話，git 會自動把它們黏在一起）

標頭

標頭也分成幾個部分：

• 類型（原則上只能是以下幾種）
  • feat：新功能 (feature)
  • fix：Bug 修復
  • refactor：重構
  • chore：無關功能/Bug 的改動（config, version ... etc）
  • docs：修改文件
  • style：修改 UI style （不影響功能）
  • test：新增/修改測試程式碼
• 範圍
  • 選填，如果這次改動限定在某個模組，或是某個跟這個 App 分類相關的區塊，可以在這裡說明
• 標題
  • 摘要，本次改動的精簡版摘要，基本上限定在一行以內寫完（可以的話不要寫太多細節）

內容

如果摘要部分無法很好的敘述，在內容的區塊可以更自由的發揮與說明。

可能包含了以下內容：

• 所有具體的改動列表
• Bug 的 Root cause 以及解釋你的 fix
• 重構的動機與思考方向
• TODOs
• 如果這是個 workaround，也可以在這裡說明，並且提醒後面要找時間修正（盡量 XD）

頁腳

基本上只有兩種情況會用到頁腳

BREAKING CHANGE

通常有一些不相容等級的改動，或是這個改動需要有別人配合著修改才能正常運作的改動，則需要特別用 BREAKING CHANGE 來註明

並且在底下詳細說明不相容的部分，影響的模塊/範圍，然後對應的修改/配合方式

Reference hook

有一些 CI 或是專案管理工具，是可以做 hook 的，所以可以在這裡標示需要 hook 的 ticket / issue number (像是 GitLab issue, JIRA number ... etc)

Sample commit

• 黃色區塊：標頭
• 綠色區塊：內容
• 藍色區塊：頁腳

---

於是乎，我們就能夠從 well-formatted 的 git commit 來自動產出漂亮的 release note

並且只要有格式，有規範。就會有自動化的工具可以使用，這邊列出一些我們團隊之前用過的一些工具

• Commitizen：可以在 CLI 上面透過選擇自動產出 angular format 的 commit，可以用來取代原本的 editor commitizen.github.io

• commitlint ：可以用來檢查 commit 的格式是否有符合規範，可以加入到 githook 裡面，確保 push 上去的 commit 都是符合格式 commitlint.js.org

• conventional-changelog ：可以把 git history 產出 Changelog / Release note 格式的工具，可以跟 CI 整合用來在產出 release build 的時候順便產出 changeling github.com