格式化 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
  • commitlint :可以用來檢查 commit 的格式是否有符合規範,可以加入到 githook 裡面,確保 push 上去的 commit 都是符合格式
  • conventional-changelog :可以把 git history 產出 Changelog / Release note 格式的工具,可以跟 CI 整合用來在產出 release build 的時候順便產出 changeling

keep learning; keep coding; keep debugging;

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store