過去曾經整理過如何透過 semantic-release 這套工具整合 CI/CD 來達到自動化更新套件版號、產生 CHANGELOG 檔，並發佈到 npm 的流程。
當時雖然有提到 conventional commit 這個撰寫 commit message 的規範（convention），但還沒有實際透過一些好用的工具來建立 commit message 和針對 commit message 進行檢查。
在這篇文章中就來介紹幾套用來建立符合 conventional commit 的好用工具：
- 透過 commitlint 進行 commit message 的檢查（lint）
- 搭配 husky 在建立 commit message 前就自動執行 commitlint
- 透過 commitizen 方便開發者建立符合 conventional commit 的 commit message
- 使用 conventional-changelog 根據 commit message 來產生 CHANGELOG 檔
- 使用 standard version 來同時更新版本號和產生 CHANGELOG 檔
如果是對於 CI/CD 中如何自動更新版號的部分，則可以參考過去寫的系列文章：發佈 npm 套件 - 從手動到自動。
commitlint：檢查 commit message
commitlint 這套工具是用來作為 git commit 的 linter，並且可以搭配不同的 convention。
這裡選擇 config-conventional，也就是需要依據 conventional commit 的規範來寫 commit message：
- @commitlint/cli 是用來執行 commitlint 的工具
- @commitlint/config-conventional 是根據 conventional commit 所建立的規範
初次安裝
# 安裝 commitlint-cli 和 config-conventional npm install --save-dev @commitlint/{config-conventional,cli} # 會在專案中建立 commitlint.config.js 並放入設定 echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
使用
# 使用 commitlint $ echo "add commitlint" | npx commitlint > ✖ subject may not be empty [subject-empty] > ✖ type may not be empty [type-empty]
如果這個 commit message 不符合規範的話，會跳出錯誤：
搭配 husky
但和 eslint 類似，如果不能在建立 git commit message 時就自動檢查規則的話，這個工具就會變得有點冗，這時候可以搭配 husky 這套工具。
# 第一次安裝 husky 才需要執行 $ npx husky-init && npm install # 建立 commitlint 用的 git hook npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'
husky 這套工具可以讓開發者在不同的 git hook 執行不同的動作，例如在建立 commit 前（pre-commit）執行 ESLint 的檢查，如果檢查沒過就不能建立該次 commit。
這裡則是利用 husky 在 commit-msg 這個 git hook 去檢查 commit message 有沒有符合 conventional commit 的規範。這時打開專案中的 .husky/commit-msg，應該會長這樣：
#!/bin/sh . "$(dirname "$0")/_/husky.sh" npx --no-install commitlint --edit $1
預設執行 npx husky-init && npm install 的指令後，husky 會自動在 .husky 資料夾中建立 pre-commit 的檔案，它會告訴 husky 在建立 git commit 前去執行 npm test 的指令。但如果是 create-react-app 的專案，因為預設 npm test 會執行的是 watch mode，因此需要改成 npm test -- --watchAll=false。
這時候在建立 commit message 是就會自動使用 commitlint 進行檢查，如果不符合規範的話，就無法成功建立 commit：
commitizen：建立 commit message
除了可以用 commitlint 搭配 husky 來檢查 commit message 之外，再來很重要的就是要能夠簡單方便的建立符合 conventional commit 的 message。因此就有幫助開發者建立 conventional commit message 的好用工具。
其中 commitizen 是同事 Ken 推薦非常多人使用的工具，它用起來的體驗蠻不錯的。另一套則是 commitlint 本身提供的 @commitlint/prompt-cli。
commitizen（較推）
commitizen 是非常多人使用的的工具，相較於 @commitlint/prompt-cli 用起來感覺更友善一些：
# 安裝 npx commitizen init cz-conventional-changelog --save-dev --save-exact # 之後要建立 commit 的話，只需要執行 npx cz
@commitlint/prompt-cli
除了可以使用 commitizen 外，也可以使用 @commitlint/prompt-cli 來輔助我們建立 git commit message，但基本上挑一套使用就可以了。
# 初次安裝 npm install --save-dev @commitlint/prompt-cli
安裝完後執行：
# 建立 commit message
npx commit
就會跳出對應的 CLI 工具來協助建立 git commit：
conventional-changelog：建立 CHANGELOG
在根據 conventional commit 來寫 commit message 後，我們還可以自動產生對應的 CHANGELOG 檔。這裡則會使用 conventional-changelog-cli。
只需要執行：
- -p angular：如果有使用 conventional commit 來建立 commit message 的話，就可以加上此選項。它會用符合 conventional message 的內容來產生 CHANGELOG；如果沒加此參數的話，所有 git message 都會進到 changelog 中。
# 第一次安裝 $ npm install --save-dev conventional-changelog-cli # 檢視可以使用的 options 和說明 $ npx conventional-changelog --help # 第一次產生 CHANGELOG npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0 # 將新的更新 message 添加到 CHANGELOG npx conventional-changelog -p angular -i CHANGELOG.md -s
也可以把產生 CHANGELOG 的指令放到 package.json 的 scripts 中：
diff --git a/package.json b/package.json index 18f0899..37a1d41 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,7 @@ "scripts": { "build": "react-scripts build", "test": "react-scripts test", "eject": "react-scripts eject", + "changelog": "conventional-changelog -i CHANGELOG.md -s, "lint:staged": "lint-staged", "prepare": "husky install" }, @@ -51,6 +52,7 @@ "devDependencies": { "@commitlint/cli": "^12.1.4", "@commitlint/config-conventional": "^12.1.4", + "conventional-changelog-cli": "^2.1.1", "cz-conventional-changelog": "^3.3.0", "husky": "^7.0.0", "lint-staged": "^11.0.0"
之後就只需要執行 npm run changelog 就會產生最新的 CHANGELOG 檔。
standard version：更新套件版本號
最後這套 standard version 是在針對套件進行版號更新，並同時產生該次更新的 CHANGELOG 檔，也就是說不需要再額外使用上述 conventional-changelog 的工具。
如果你產生 CHANGELOG 的時間都是在更新版本號時，且是使用 conventional commit 在建立 commit message 的話，則可以用 standard version 就好，不用再使用 conventional-changelog。
它會：
- 根據 conventional commit 的內容，依據 semver 的原則來更新版號
- 產生對應的 CHANGELOG
# 檢視所有可用的指令 npx standard-version --help # 第一次 release npx standard-version --first-release # 更新套件版號和 CHANGELOG npx standard-version # 透過 dry-run 先看看會有什麼改變 npx standard-version --dry-run # 更新到指定的版本 npx standard-version --release-as minor # 指定更新 minor 的版號 npx standard-version --release-as 1.1.0 # 指定更新後的版號
需要特別留意的是，當版號還在 v0.y.z，major 還沒進到 v1 是，會被視為是 pre-production 的產品，因此 feature 和 fix 都只會更新 patch version；breaking change 則只會更新 minor version。可以參考這個 issue 的討論：Version bumping isn't working properly based on Commit types。
另外有需要的話，也可以把這個工具加到 package.json 中的 scripts 中：
diff --git a/package.json b/package.json index d18c992..9832508 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "test": "react-scripts test", "eject": "react-scripts eject", "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0", + "release": "standard-version", "lint:staged": "lint-staged", "prepare": "husky install" },
執行的話變成：
# 更新版本 npm run release # 執行 dry-run 看實際執行的話會有什麼改變 npm run release -- --dry-run
