一文搞定規範化Git Commit

怎樣的夜發表於2020-09-28

前言

規範化 git commit 對於提高 git log 可讀性、可控的版本控制和 changelog 生成都有著重要的作用。然而阻礙我們腳步的不只是團隊的推廣,單單對於一系列工具的配置都讓人頭大。這其中主要就是 commitlint 和 commitizen 的配合使用以及自定義提交規範。本文總結了目前的最佳實踐給大家,如果有幫助,賞個star足矣。

Conventional Commits 約定式提交規範

Conventional Commits 是一種用於給提交資訊增加人機可讀含義的規範。約定式提交規範是一種基於訊息的輕量級約定。它提供了一組用於建立清晰的提交歷史的簡單規則;這使得編寫基於規範的自動化工具變得更容易。這個約定與 SemVer 相吻合,在提交資訊中描述新特性、bug 修復和破壞性變更。
提交說明的結構如下所示:

型別(type)

feat:: 型別為 feat 的提交表示在程式碼庫中新增了一個功能(這和語義化版本中的 MINOR 相對應)。
fix::型別為 fix 的 提交表示在程式碼庫中修復了一個 bug (這和語義化版本中的 PATCH 相對應)。
docs:: 只是更改文件。
style:: 不影響程式碼含義的變化(空白、格式化、缺少分號等)。
refactor:: 程式碼重構,既不修復錯誤也不新增功能。
perf:: 改進效能的程式碼更改。
test:: 新增確實測試或更正現有的測試。
build:: 影響構建系統或外部依賴關係的更改(示例範圍:gulp、broccoli、NPM)。
ci:: 更改持續整合檔案和指令碼(示例範圍:Travis、Circle、BrowserStack、SauceLabs)。
chore:: 其他不修改src或test檔案。
revert:: commit 回退。

範圍(scope)

可以為提交型別新增一個圍在圓括號內的作用域,以為其提供額外的上下文資訊。例如 feat(parser): adds ability to parse arrays.。

BREAKING CHANGE

在可選的正文或腳註的起始位置帶有 BREAKING CHANGE: 的提交,表示引入了破壞性 API 變更(這和語義化版本中的 MAJOR 相對應)。 破壞性變更可以是任意 型別 提交的一部分。

示例

包含了描述以及正文內有破壞性變更的提交說明
feat: allow provided config object to extend other configs

BREAKING CHANGE: extends key in config file is now used for extending other config files

包含了可選的 ! 字元以提醒注意破壞性變更的提交說明
chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

不包含正文的提交說明
docs: correct spelling of CHANGELOG

包含作用域的提交說明
feat(lang): add polish language

為 fix 編寫的提交說明,包含(可選的) issue 編號

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

約定式提交規範

  1. 每個提交都必須使用型別欄位字首,它由一個名片語成,諸如feat或fix,其後接一個可選的作用域欄位,以及一個必要的冒號(英文半形)和空格。
  2. 當一個提交為應用或類庫實現了新特性時,必須使用feat型別。
  3. 當一個提交為應用修復 bug 時,必須使用fix型別。
  4. 作用域欄位可以跟隨在型別欄位後面。作用有必須是一個描述某部分程式碼的名詞,並用圓括號包圍,例如:fix(parser):
  5. 描述欄位必須緊接在型別/作用域字首的空格之後。描述指的是對程式碼變更的簡短總結,例如:fix:array parsing issue
    when multiplejspaces were contained in string。
  6. 在簡短描述之後,可以編寫更長的提交正文,為程式碼變更提供額外的上下文資訊。正文必須起始於描述欄位結束的一個空行後。
  7. 在正文結束的一個空行之後,可以編寫一行或或多行腳註。腳註必須包含關於提交的元資訊,例如:關聯的合併請求、Reviewer、破壞性變更、每條元資訊一行。
  8. 破壞性變更必須標示在正文區域最開始處,或腳註區域中某一行的開始。一個破壞性變更必須包含大寫的文字BREAKING
    CHANGE,後面緊跟冒號和空格。
  9. 在BREAKING CHANGE:之後必須提供描述,以描述對 API 的變更。例如:BREAKING CHANGE:
    enviroment variables now take precedence over cofig files。
  10. 在提交說明中,可以使用feat和fix之外的型別。
  11. 工具的實現必須不區分大小寫地解析構成約定式提交的資訊單元,只有BREAKING CHANGE 必須是大寫的。
  12. 可以在型別/作用域字首之後,:之前,附加!字元,以進一步提醒注意破壞性變更。當有!字首時,正文或腳註內必須包含BREAKING
    CHANGE: description

為什麼使用約定式提交

  1. 自動化生產 CHANGELOG。
  2. 基於提交的型別,自動決定語義化的版本變更。
  3. 向同事、公眾與其他利益關係者傳達變化的性質。
  4. 觸發構建和部署流程。
  5. 讓人們探索一個更加結構化的提交歷史,以便降低對你的專案作出貢獻的難度。

cz-customizable

可自定義的Commitizen外掛(或獨立實用執行)可幫助實現一致的提交訊息。
安裝 cz-customizable:
$ yarn add cz-customizable -D
複製程式碼
向 package.json 新增新的 script:
{
“scripts” : {

“commit”: “./node_modules/cz-customizable/standalone.js”
}
}

在根目錄新建 .cz-config.js 並複製 cz-config-EXAMPLE.js 到檔案。
效果:

commitlint
commitlint檢查您的提交訊息是否符合conventional commit format。
1、安裝 @commitlint/cli、husky:
$ yarn add -D @commitlint/cli husky

2、新增 git commit hooks 到 package.json:
{

“husky”: {
“hooks”: {
“commit-msg”: “commitlint -E HUSKY_GIT_PARAMS”
}
}
}

3、安裝 commitlint-config-cz:
commitlint-config-cz 合併 cz-customizable 的配置 {types,scopes,scopeOverrides} 和 commitlint 的配置 {type-enum,scope-enum}。這樣,你就可以在一個地方維護 types 和 scopes。
$ yarn add commitlint-config-cz -D
複製程式碼
4、在 commitlint.config.js 中用 cz 擴充套件您的 commitlint 配置:
module.exports = {
extends: [‘cz’],
rules: {
// must add these rules
‘type-empty’: [2, ‘never’],
‘subject-empty’: [2, ‘never’]
}
};

vscode commitizen
在 VS Code 中搜尋裝 vscode commitizen,然後就可以擺脫命令列了,而且這個外掛是和前面所有的配置相容的,效果如下:

GitHub Actions
新建一個 github workflow .github/workflows/commitlint.yml,作用是在提交 pull_request 時,檢查資訊:
name: Lint Commit Messages
on: [pull_request]

jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- uses: actions/setup-node@v1
with:
node-version: ‘10.x’
- run: npm install
- name: Add dependencies for commitlint action
# G I T H U B W O R K S P A C E i s t h e p a t h t o y o u r r e p o s i t o r y r u n : e c h o " : : s e t − e n v n a m e = N O D E P A T H : : GITHUB_WORKSPACE is the path to your repository run: echo "::set-env name=NODE_PATH:: GITHUBWORKSPACEisthepathtoyourrepositoryrun:echo"::setenvname=NODEPATH::GITHUB_WORKSPACE/node_modules"
# Now the commitlint action will run considering its own dependencies and yours as well ?
- uses: wagoid/commitlint-github-action@v2

standard-version
standard-version 是一款遵循語義化版本( semver)和 commit message 標準規範 的版本和 changelog 自動化工具。通常情況線下,我們會在 master 分支進行如下的版本釋出操作:

git pull origin master
根據 package.json 中的 version 更新版本號,更新 CHANGELOG
git add .
git commit
git tag 打版本操作
git push --tags:push 版本 tag 和 master 分支到倉庫

其中 2,3,4,5 是 standard-version 工具會自動完成的工作,配合本地的 shell 指令碼,則可以自動完成一系列版本釋出的工作了。

安裝 & 使用

$ yarn add -D standard-version

// package.json
{
“scripts”: {
“release”: “standard-version”
}
}

First Release:yarn release --first-release
Cutting Release:yarn release
Release as a Pre-Release:yarn release --prerelease or yarn release --prerelease alpha
Release as a Target Type Imperatively (npm version-like):yarn release --release-as minor or yarn release --release-as 1.1.0,可以合併 --prerelease以此方便釋出實驗性特性
Prevent Git Hooks:yarn release --no-verify

相關文章