約定式提交 Conventional Commits

一些心酸血淚

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

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

First Beautiful Commit

Fix again

Another one

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

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

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

基本上大概會是這樣…

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

類型

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

• feat：新功能。
• fix：修復 bug。
• docs：文件。
• style：coding style 的調整，例如：空白、分號、空格等，不影響程式碼的內容。
• refactor：重構現有程式碼，不屬於新增新功能或是修 bug。
• perf：提升效能的改進。
• test：新增或修改測試。
• build：和打包或外部依賴相關的修改，例如：npm、gulp、broccoli。
• ci：與 CI 設定檔或 script 相關的修改，例如：Travis、Circle、BrowserStack、SauceLabs。
• chore：其他，並且也不會修改原始碼或是測試，例如：storybook 的新增或變更。
• revert：回復前一個提交的 commit。

影響範圍

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

例如：本次修改是關於某個 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 專案安裝，這樣就可以真正的落實 強制 團隊好好使用。

• commitizen：CLI 工具，利用互動問答方式填寫提交內容。
• cz-conventional-changelog：互動問答的內容。
• standard-version：訂定版號的工具。

安裝。

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

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

如何自動生成 Change Log

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

主要的差異是

• 主版號：表示這個版本的新增功能與先前的 API 不相容。
• 次版號：表示這個版本的新增功能與先前的 API 可相容。
• 修訂號：表示這個版本的問題修正與先前的 API 可相容。

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

• 方法一：使用 standard-version 生成 changelog。
• 方法二：使用 conventional-changelog-cli 生成 changelog。

這裡以 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 能有固定的格式，有助於

• 工程師在做 code review 或未來 debug 時較好閱讀前因後果。
• 便於自動生成 change log。

參考資料

• 約定式提交 - 一種用於增加提交說明之人機可讀性意義的規範