格式化 Git commit message — Angular format

mf99
mf99
Dec 4, 2019 · 5 min read

工作上大家經常會使用到版本管理軟體,大多數使用的都是 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 的格式是否有符合規範,可以加入到 裡面,確保 push 上去的 commit 都是符合格式
  • conventional-changelog :可以把 git history 產出 Changelog / Release note 格式的工具,可以跟 CI 整合用來在產出 release build 的時候順便產出 changeling
mf99

Written by

mf99

keep learning; keep coding; keep debugging;

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade