規範你的 commit message 而且根據 commit 自動生成 CHANGELOG.md

時間 2019-11-07

標籤規範 commit message 而且根據自動生成 changelog.md changelog 简体版

原文原文鏈接

項目地址： github.com/sunshine940…node

一個好的項目一般都是多人合做的結果，然而每一個人有每一個人的開發習慣，並不統一。git

因此 commit message 就顯得格外的重要。有些不規範的 commit 可能過個一個月以後你本身都不知道當時的提交目的了ﾍ(;´Д｀ﾍ)，github

因此，爲了能使得往後復（zhao）盤（guo）的時候更加的方便，團隊之間遵照同一套 commit message 規範仍是頗有必要的。npm

本篇文章介紹的是 Angular 規範，這是目前使用最廣的寫法，比較合理和系統化，而且有配套的工具。json

`commit message` 的做用

提供更多的歷史信息，方便快速瀏覽。
能夠過濾某些commit（好比文檔改動），便於快速查找信息。
能夠直接從commit生成Change log。

`commit message` 的格式

剛剛有說到，咱們使用的是 Angular 規範，下面來大體介紹下：bash

使用 git commit 能夠提交多行 commit message.ide

commit message 包括三個部分：Header，Body 和 Footer工具

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
複製代碼

其中，Header 是必填，Body 和 Footer 是選填。測試

`Header`

Header 包括三個字段：type（必填）、scope（選填）和 subject（必填）優化

`type`

type 用於說明 commit 的類別，只容許使用下面 7 個標識。

feat：新功能（feature）
fix：修補bug
docs：文檔（documentation）
style：格式（不影響代碼運行的變更）
refactor：重構（即不是新增功能，也不是修改bug的代碼變更）
test：增長測試
chore：構建過程或輔助工具的變更

type 爲 feat 和 fix，則該 commit 將確定出如今 Change log 之中。

`scope`

scope 用於說明 commit 影響的範圍，好比數據層、控制層、視圖層等等，視項目不一樣而不一樣。

`subject`

subject 是 commit 目的的簡短描述，不超過50個字符

以動詞開頭，使用第一人稱如今時，好比 change，而不是 changed 或 changes
第一個字母小寫
結尾不加句號（.）
複製代碼

`body`

Body 部分是對本次 commit 的詳細描述，能夠分紅多行。下面是一個範例。

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent
複製代碼

`Footer`

Footer 部分只用於兩種狀況

不兼容變更

若是當前代碼與上一個版本不兼容，則 Footer 部分以 BREAKING CHANGE 開頭，後面是對變更的描述、以及變更理由和遷移方法。

關閉 Issue 若是當前 commit 針對某個 issue，那麼能夠在 Footer 部分關閉這個 issue

Closes #123, #245, #992
複製代碼

`Commitizen` -- 自動生成合格的 `commit message`

根據上述的描述，你是否是在感慨寫個 commit message 好麻煩，這裏介紹下 Commitizen -- 可以根據提示自動生成符合規範的 commit message

安裝

$ npm install -g commitizen
複製代碼

在項目中使用

而後，在項目目錄裏，運行下面的命令，使其支持 Angular 的 Commit message 格式。

$ commitizen init cz-conventional-changelog --save --save-exact
複製代碼

commit

在提交的時候就可使用 git cz 就能夠根據提示，生成自動化的 commit message

`validate-commit-msg` 檢查你的 `commit-message` 規範

Commitizen 能夠幫助咱們規範本身的 commit-message，可是在團隊合做中，如何規範其餘成員的 commit 規範呢？

可使用 validate-commit-msg 來檢查你的項目的 commit-message 是否符合格式

`validate-commit-msg` 安裝

npm install --save-dev validate-commit-msg
複製代碼

`husky` 安裝

按照 validate-commit-msg 中 README 中寫的，能夠用 validate-commit-msg 做爲一個 githook 來驗證提交消息，而且推薦了 husky。

This provides you a binary that you can use as a githook to validate the commit message. I recommend husky. You'll want to make this part of the commit-msg githook, e.g. when using husky, add "commitmsg": "validate-commit-msg" to your npm scripts in package.json.

執行

npm install husky --save-dev
複製代碼

而且在 package.json 中的 scripts 字段中加入

"commitmsg": "validate-commit-msg"
複製代碼

而後每次 git commit 以後，就會自動檢查 commit message 是否合格。若是不合格，就會報錯

husky > commit-msg (node v9.2.1)
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
change
husky > commit-msg hook failed (add --no-verify to bypass)
複製代碼

生成 Change log

若是你的全部 commit 都符合 Angular 格式，那麼發佈新版本時， Change log 就能夠用腳本自動生成。

生成的文檔包括如下三個部分。

New features
Bug fixes
Breaking changes.

每一個部分都會羅列相關的 commit ，而且有指向這些 commit 的連接。固然，生成的文檔容許手動修改，因此發佈前，你還能夠添加其餘內容。

`conventional-changelog` 自動根據 `commit` 生成 `change log`

`conventional-changelog` 安裝

npm install -g conventional-changelog-cli
複製代碼

`conventional-changelog` 工做流

Make changes
Commit those changes
Make sure Travis turns green
Bump version in package.json
conventionalChangelog
Commit package.json and CHANGELOG.md files
Tag
Push

conventionalChangelog 這一步有兩種選擇

# 不會覆蓋之前的 Change log，只會在 CHANGELOG.md 的頭部加上自從上次發佈以來的變更
$ conventional-changelog -p angular -i CHANGELOG.md -s -p 

# 生成全部發布的 Change log
$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0
複製代碼

注意：

這裏安裝的是 conventional-changelog-cli，安裝 conventional-changelog 會報 conventional-changelog: command not found 的錯誤
查閱了不少文章使用的是 conventional-changelog -p angular -i CHANGELOG.md -w，這樣只能在命令行中 log 出 CHANGELOG 的內容，不會生成文件，若是要生成文件須要使用 conventional-changelog -p angular -i CHANGELOG.md -s。更多的 config 可使用 conventional-changelog --help 查看
還須要注意的是，在生成 changlog 以前，須要先使用 $ npm version [version] 更改版本號，而後再生成 changelog，這一步不少的博文都沒有寫，就會致使增量生成的 CHANGELOG 一直都有以前的 commit 記錄。

自動判斷版本號

上面步驟有兩個須要優化的地方

須要在 conventionalChangelog 以前先要更改版本號
生成 CHANGELOG.md 以後又形成了新的改動，因此還須要再執行一遍提交

因此咱們須要自動化的執行這些，commitizen 還依據 conventional message，建立起一個生態

conventional-changelog-cl：經過提交記錄生成 CHANGELOG.md
conventional-github-releaser：經過提交記錄生成 github release 中的變動描述
conventional-recommended-bump：根據提交記錄判斷須要升級 Semantic Versioning 哪一位版本號

使用這些工具能夠簡化發佈流程。

cp package.json _package.json &&
preset=`conventional-commits-detector` && 
echo $preset &&
bump=`conventional-recommended-bump -p angular` &&
echo ${1:-$bump} &&
npm --no-git-tag-version version ${1:-$bump} &>/dev/null &&
conventional-changelog -i CHANGELOG.md -s -p ${2:-$preset} &&
git add CHANGELOG.md package.json package-lock.json &&
version=`cat package.json` &&
git commit -m'docs(CHANGELOG): $version' &&
mv -f _package.json package.json &&
npm version ${1:-$bump} -m 'chore(release): %s' &&
git push --follow-tags 
複製代碼

在你的項目中規範 `commit message` 而且根據 `commit` 自動生成 `CHANGELOG.md`

安裝依賴

npm install -g commitizen conventional-changelog conventional-changelog-cli conventional-commits-detector conventional-recommended-bump husky validate-commit-msg

複製代碼

安裝完成以後版本以下（我遇到過 conventional-recommended-bump 是 4.x 的版本會報錯Error: Unable to load the "angular" preset package. Please make sure it's installed.。下降下版本就好。

/usr/local/lib
├── commitizen@3.0.4
├── conventional-changelog@2.0.3
├── conventional-changelog-cli@2.0.5
├── conventional-commits-detector@0.1.1
├── conventional-recommended-bump@0.3.0
└── npm@6.1.0
複製代碼

在 package.json 中增長 script 字段

"changelog": "cp package.json _package.json &&preset=`conventional-commits-detector` && echo $preset && bump=`conventional-recommended-bump -p angular` && echo ${1:-$bump} && npm --no-git-tag-version version ${1:-$bump} &>/dev/null && conventional-changelog -i CHANGELOG.md -s -p ${2:-$preset} && git add CHANGELOG.md package.json package-lock.json && version=`cat package.json` && git commit -m'docs(CHANGELOG): $version' && mv -f _package.json package.json && npm version ${1:-$bump} -m 'chore(release): %s' && git push --follow-tags "
複製代碼