約定式提交 Conventional Commits

一些心酸血淚

由於最近發現團隊內(到底從哪兒來的)的工程師會開始提交一些不知所云的提交描述,因此開始讓專案使用「約定式提交」(conventional commits)。

先貼幾個實際例子讓大家瞧瞧 (  ̄ 3 ̄)y▂ξ

First Beautiful Commit

conventional commits

Fix again

conventional commits

Anoter one

conventional commits

以上這些提交描述「First Beautiful Commit」、「Fix again」、「Anoter one」都無法讓未來追程式碼的人立刻理解「改了什麼」和「為何要這樣修改」。因此,導入約定式提交能讓團隊成員強制遵守固定的規範和格式,填寫適當的內容。

撰寫符合「約定式提交」的提交描述

遵守「約定式提交」的提交描述,是長什麼樣子呢?

基本上大概會是這樣…

類型 (影響範圍):短描述 #issue_number

類型

本次修改的類型,後接一個冒號與空白 :

影響範圍

影響範圍可以是元件、檔名或或特定的功能,會用括號括起來。

例如:本次修改是關於某個 device list table 的調整,影響範圍就可以寫 device list table。

關於本次修改的短描述

以命令方式撰寫的短描述,工具會協助規範字數。

例如:承上,本次修改是關於某個 device list table 的調整,並且是調整其欄位寬度的設定,這樣短描述就可以寫「update table column width settings」。

關於本次修改的長描述

若有更多資訊,則可填寫至此,但通常我會略過,改寫在 CL (i.e.,) 裡面,可參考這裡

Breaking Changes

若是重大修改則必須詳細填寫其描述,注意,「BREAKING CHANGE」必須是全大寫。

範例如下,填寫類型、影響範圍(在括號內)、短描述,接著標記是「BREAKING CHANGE」並在其後寫上描述「re-define table setting config」,最後若有相關 issue 也可填上。

feat (device list table): update table column width settings #123

BREAKING CHANGE: re-define table setting config

#123

Issue

若與某個 issue 有關連,則必須填寫 issus numer,例如:#123。


依照以上步驟,會得到的提交會這樣的:「feat (device list table): update table column width settings #123」。由於有了規範與工具,因此就能解決本文一開始提到的「提交一些不知所云的提交描述」的問題了。

工具

若用人工的方式硬記規則就太辛苦了,接下來看一些能幫助我們產生約定式提交的工具。

安裝以下工具,建議 by 專案安裝,這樣就可以真正的落實 強制 團隊好好使用。

安裝。

yarn add commitizen cz-conventional-changelog standard-version

package.json 設定

"scripts": {
  "commit": "git-cz",
  "release": "standard-version",
  ...
},
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

之後可以再做 git hooks 設定來做格式檢驗。

接著就這樣下指令就可以用了。

yarn commit

依照互動問答填寫要提交的內容。

conventional commits

如何自動生成 Change Log

版號到底要怎麼訂?語意化版本 (semantic versioning) 這裡定義了何時要更新主版號、次版號和修訂版,這樣就能得知本次調整到底會有何影響。

主要的差異是

繼續回到自動生成 change log 的議題上…出 build 的時候需要要列出到底改了什麼,人工記錄當然可以,但能自動產出不是更好?

這裡以 standard-version 為主。

若想要自動生成 change log,則 package.json 要這樣設定…

"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md",
  "release:major": "standard-version --release-as major",
  "release:minor": "standard-version --release-as minor",
  "release:patch": "standard-version --release-as patch",
  "release": "standard-version"
},

下指令後就可以自動產生 change log,得到一個 CHANGELOG.md 檔案。

release 是增加大版號,若想遵循 semantic versioning 則可利用其它指令 - major 表示要更新大版號,minor 表示更新小版號,而 patch 則是更新修訂版,也可以自行輸入版號來做設定,點此看說明。

yarn release

總結

約定式提交讓 commit 能有固定的格式,有助於

參考資料


comments powered by Disqus