目錄
引子
在 github 上逛逛就可以發現，其提交的 commit 都有一定格式，工作中也有相應的規定，時間長了就能體會到其中的好處。這種約束是一種良好的實踐。抽出一些時間，更詳細的了解相關的資料，然后做了一些實踐和總結。
規范 Commit 的好處
- 提供更明確的歷史信息，方便判斷提交目的和瀏覽
- 可以過濾某些不必要的提交，方便快速查找信息
- 自動化生成 Changelog
- 向同事、公眾與其他利益關系人傳達變化的性質
- 基於提交的類型，自動決定語義化的版本變更
以上的好處，個人認為要有一個大的前提，就是每一個提交，盡量保證其目的單一性，比如說幾個 bug 看似類似，就一次性修改提交。這樣做，讓 commit 的信息變的復雜化，閱讀不方便，也容易讓人想到一些不必要的關聯性。
Commit 的格式
找了幾個 start 較多的庫，看看提交的格式。
網上推薦的寫法是第 2 和 3 種，也就是 Angular 規范，並有配套的工具。有一個文檔對 commit 的格式要求有個描述叫約定式提交。下面就根據 Angular 規范和對應文檔，看看詳細的說明。
每個 commit message 包含一個 header，body 和 footer。header 有一個特殊的格式包含有 type，scope 和 subject：
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
header、body、footer 之間都要空一行，header 是必填項，scope 是選填項。commit message 的每一行的文字不能超過 100 個字符。這樣子在 github 和 git 工具上更便於閱讀。
Type
type 用於說明 commit 的類別，必須為以下類型的一種：
- feat: 新的功能
- fix: 修復 bug
- docs: 只是文檔的更改
- style: 不影響代碼含義的更改 (例如空格、格式化、少了分號)
- refactor: 既不是修復 bug 也不是添加新功能的代碼更改
- perf: 提高性能的代碼更改
- test: 添加或修正測試
- chore: 對構建或者輔助工具的更改，例如生成文檔
Scope
scope 用於說明 commit 影響的范圍，當影響的范圍有多個時候，可以使用 *。
Subject
subject 用於對 commit 變化的簡潔描述：
- 使用祈使句，一般以動詞原形開始，例如使用 change 而不是 changed 或者 changes
- 第一個字母小寫
- 結尾不加句號（.）
Body
body 用於對 commit 詳細描述。使用祈使句，一般以動詞原形開始，例如使用 change 而不是 changed 或者 changes。
body 應該包含這次變化的動機以及與之前行為的對比。
Footer
footer 目前用於兩種情況。
1 不兼容的變動
所有不兼容的變動都必須在 footer 區域進行說明，以 BREAKING CHANGE: 開頭，后面的是對變動的描述，變動的理由和遷移注釋。
BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
myBind: 'bind',
myExpression: 'expression',
myEval: 'evaluate',
myAccessor: 'accessor'
}
After:
scope: {
myAttr: '@',
myBind: '@',
myExpression: '&',
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
2 關閉 issue
如果 commit 是針對某個 issue，可以在 footer 關閉這個 issue。
## 關閉單個
Closes #234
## 關閉多個
Closes #123, #245, #992
Revert
如果 commit 用於撤銷之前的 commit，這個 commit 就應該以 revert: 開頭，后面是撤銷這個 commit 的 header。在 body 里面應該寫 This reverts commit <hash>.，其中的 hash 是被撤銷 commit 的 SHA 標識符。
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
示例
feat($browser): onUrlChange event (popstate/hashchange/polling)
Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available
Breaks $browser.onHashChange, which was removed (use onUrlChange instead)
fix($compile): couple of unit tests for IE9
Older IEs serialize html uppercased, but IE9 does not
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.
Closes #351
style($location): add couple of missing semi colons
docs(guide): updated fixed docs from Google Docs
Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace
Commit 相關的工具
填寫提示工具 commitizen
這個工具是用來給 commit 一個引導的作用，根據提示一步一步的完善 commit。
在 Windows 環境下安裝，個人遇到的問題有：
1、安裝 commitizen 后，進行初始化，找不到命令
嘗試成功的解決方法是用 yarn 執行指令:
yarn commitizen init cz-conventional-changelog --save-dev --save-exact
2、按照說明里面直接執行 npx git-cz無效，安裝了 npx 也無效
發現在 node_modules\bin\ 目錄下，並沒有 npx 相關可執行文件，需要安裝 npx。
安裝后還是無效，需要用 yarn 來執行指令
yarn npx git-cz
可以發現執行指令后，顯示了對應的可執行文件的路徑。
如果配置了 scripts，那么提交的時候需要執行對應的指令，才會觸發這個工具的作用。
還有操作的問題，在自己的戴爾筆記本用上下鍵切換無效，也嘗試過各種組合鍵，也是無效，外接的鍵盤有效。
格式校驗工具 commitlint
原 validate-commit-msg 已不被推薦使用。安裝對應要使用的提交規范，
#it also works for Windows
yarn add @commitlint/{config-conventional,cli} --dev
# Configure commitlint to use angular config
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
示例用的是 config-conventional 規范，這個安裝后，還需要使用 commitmsg hook，推薦使用 husky。安裝husky
yarn add husky --dev
然后配置 package.json
{
"scripts": {
"commitmsg": "commitlint -E GIT_PARAMS"
}
}
提交時候就會觸發校驗，效果如下圖。
2018.12.09：
在最新的版本中，由於 GIT_PARAMS 參數的問題，進行了更新，配置變化如下：
{
"scripts": {
- "precommit": "npm test",
- "commitmsg": "commitlint -E GIT_PARAMS"
},
+ "husky": {
+ "hooks": {
+ "pre-commit": "npm test",
+ "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+ }
+ }
}
或者在項目文件夾下執行下面的命令，會自動進行更正。
./node_modules/.bin/husky-upgrade
生成 Changelog 工具 Conventional Changelog
使用的工具是 Conventional Changelog，推薦使用 standard-version。commit 符合 Conventional Commits Specification 中描述的格式，就可以用程序自動生成 Changelog。
先進行安裝。
yarn add standard-version --dev
然后配置package.json配置執行的腳本。
{
"scripts": {
"release": "standard-version"
}
}
執行該腳本命令，產生的結果：生成文件 CHANGELOG、自動修改庫的版本號、產生一個 commit，用工具查看如下圖所示。
每一次執行，不會覆蓋之前的 CHANGELOG，只會在 CHANGELOG 的頂部添加新的內容。
感受
網上有很多類似的介紹，自己動手去實踐，得到的比看到的多的多。