2023 年了，還有前端人不知道 commit 規範 ？

語言: CN / TW / HK
時間 2023-03-23 10:15:05
主題:

一個開發人員需要知道的 commit 規範

什麼是約定式提交

約定式提交（Conventional Commits）是一種用於程式碼版本控制的規範，旨在通過明確和標準化提交資訊來提高程式碼協作質量和效率。其基本原則是通過規定提交資訊的結構和語義來提高程式碼版本控制的可讀性、可維護性和自動化程度。

約定式提交規範通常要求提交資訊包括一個描述性的"型別"、一個可選的"作用域"、一個用於簡潔說明的"主題"，以及可選的"正文"和"尾部"等組成部分。這些組成部分的格式和語義都是根據規範要求進行約定的，比如使用"feat"來表示新功能、"fix"表示修復錯誤、"docs"表示文件變更等。

通過遵循約定式提交規範，開發人員可以更容易地理解和管理程式碼的變更歷史，同時也為自動化工具提供了更多可靠的資訊，例如自動生成版本號、釋出日誌和程式碼庫更新等操作。

提交說明的結構如下所示:

原文：

<type>[optional scope]: <description> ​ [optional body] ​ [optional footer(s)]

譯文：

<型別>[可選 範圍]: <描述> ​ [可選 正文] ​ [可選 腳註]

提交說明包含了下面的結構化元素，以向類庫使用者表明其意圖：

  1. fix: 型別 為 fix 的提交表示在程式碼庫中修復了一個 bug（這和語義化版本中的 PATCH 相對應）。
  2. feat: 型別 為 feat 的提交表示在程式碼庫中新增了一個功能（這和語義化版本中的 MINOR 相對應）。
  3. BREAKING CHANGE: 在腳註中包含 BREAKING CHANGE: 或 <型別>(範圍) 後面有一個 ! 的提交，表示引入了破壞性 API 變更（這和語義化版本中的 MAJOR 相對應）。 破壞性變更可以是任意 型別 提交的一部分。
  4. 除 fix: 和 feat: 之外，也可以使用其它提交 型別 ，例如 @commitlint/config-conventional（基於 Angular 約定）中推薦的 build:、chore:、 ci:、docs:、style:、refactor:、perf:、test:，等等。
  5. 腳註中除了 BREAKING CHANGE: <description> ，其它條目應該採用類似 git trailer format 這樣的慣例。

其它提交型別在約定式提交規範中並沒有強制限制，並且在語義化版本中沒有隱式影響（除非它們包含 BREAKING CHANGE）。 可以為提交型別新增一個圍在圓括號內的範圍，以為其提供額外的上下文資訊。例如 feat(parser): adds ability to parse arrays.。

示例

包含了描述並且腳註中有破壞性變更的提交說明

feat: allow provided config object to extend other configs ​ BREAKING CHANGE: `extends` key in config file is now used for extending other config files

包含了 ! 字元以提醒注意破壞性變更的提交說明

feat!: send an email to the customer when a product is shipped

包含了範圍和破壞性變更 ! 的提交說明

feat(api)!: send an email to the customer when a product is shipped

包含了 ! 和 BREAKING CHANGE 腳註的提交說明

chore!: drop support for Node 6 ​ BREAKING CHANGE: use JavaScript features not available in Node 6.

不包含正文的提交說明

docs: correct spelling of CHANGELOG

包含範圍的提交說明

feat(lang): add polish language

包含多行正文和多行腳註的提交說明

fix: prevent racing of requests ​ Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. ​ Remove timeouts which were used to mitigate the racing issue but are obsolete now. ​ Reviewed-by: Z Refs: #123

type 型別概覽

| 值 | 描述 | | -------- | ---------------------------------------------------------- | | feat | 新增一個功能 | | fix | 修復一個Bug | | docs | 文件變更 | | style | 程式碼格式（不影響功能，例如空格、分號等格式修正） | | refactor | 程式碼重構 | | perf | 改善效能 | | test | 測試 | | build | 變更專案構建或外部依賴（例如scopes: webpack、gulp、npm等） | | ci | 更改持續整合軟體的配置檔案和package中的scripts命令，例如scopes: Travis, Circle等 | | chore | 變更構建流程或輔助工具 | | revert | 程式碼回退 |

作者：子弈 連結：https://juejin.cn/post/6844903831893966856 來源：稀土掘金 著作權歸作者所有。商業轉載請聯絡作者獲得授權，非商業轉載請註明出處。

為什麼需要約定式提交？

Git提交資訊需要遵循Angular約定是為了使提交資訊格式清晰、易於閱讀和理解，從而提高程式碼協作的效率。Angular約定包括以下三個部分：

  1. 標題（header）：用一行簡短的描述來總結更改內容，並使用特殊關鍵字指定更改型別和影響範圍。
  2. 正文（body）：提供更詳細的更改描述，包括更改原因、影響和解決方案等資訊。
  3. 頁尾（footer）：提供一些附加資訊，如相關連結、關聯的BUG編號等。

通過遵循Angular約定，可以使提交資訊更加規範化和易於管理，從而方便其他團隊成員閱讀和理解更改的含義，從而提高團隊協作效率。此外，遵循Angular約定的提交資訊還可以更好地與許多自動化工具進行整合，如自動化版本控制、程式碼審查工具等。

如何遵守約定式提交？

第一步：自動生成提交說明的工具

Commitizen是一個基於命令列的互動式工具，它可以幫助開發者規範化提交Git提交資訊，符合Angular Commit Message Conventions的規範，從而更好地管理程式碼變更歷史。

Commitizen提供了一個友好的命令列互動介面，讓開發者根據規範選擇提交資訊的型別、影響範圍等內容，自動生成符合規範的Git提交資訊。

Commitizen可以與Git結合使用，使得開發者可以使用commitizen命令代替git commit命令提交程式碼變更，並且生成的提交資訊格式更加規範化和易於管理。

這裡我建議您全域性安裝

pnpm install -g commitizen pnpm install -g cz-conventional-changelog

隨後在電腦使用者根目錄穿件.czrc檔案，不然使用的時候會進入命令列（筆者的系統為Ubuntu20.04）

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

隨後使用commitizen生成符合AngularJS規範的提交說明

commitizen init cz-conventional-changelog --save --save-exact

隨後你就可以使用以下命令獲得中規中距的commit資訊了。

git cz

第二步：客製化自動提交資訊

cz-customizable是Commitizen的一個外掛，可以幫助開發者自定義符合Angular Commit Message Conventions的提交資訊格式和內容。

拜託，人又不是機器！別那麼死板。和程式碼打交道最重要的事情就是懂得如何苦中作樂，在遇到挑戰和困難時，優秀的人能夠採取積極的心態，並且能夠尋找解決問題的方式和方法。

cz-customizable提供了一些配置選項，讓開發者可以根據專案的需要自定義提交資訊的格式和內容。

cz-customizable的配置選項包括：

  1. types: 定義提交資訊的型別，如feat（新功能）、fix（修復Bug）等。
  2. scopes: 定義提交資訊的影響範圍，如模組、元件等。
  3. allowCustomScopes: 是否允許自定義影響範圍。
  4. scopeOverrides: 定義不同型別的提交資訊對影響範圍的要求。
  5. messages: 定義提交資訊的模板，包括標題、正文、頁尾等內容。
  6. allowBreakingChanges: 是否允許提交破壞性變更。

1. 安裝 cz-customizable

npm install cz-customizable --save-dev

2. 新增以下配置到package.json中

"config": {    "commitizen": {    "path": "node_modules/cz-customizable"   } }

3.專案根目錄下建立.cz-config.js檔案來自定義提示

├── CHANGELOG.md ├── commitlint.config.js ├── index.html ├── node_modules ├── package.json ├── pnpm-lock.yaml ├── public ├── README.md ├── src ├── tsconfig.json ├── tsconfig.node.json ├── vite.config.ts └── .cz-config.js // 建立

以下是我的一些參考配置

module.exports = { // 可選型別 types: [   {     value: ':sparkles: feat',     name: '✨ feat:     新功能'   },   {     value: ':bug: fix',     name: '🐛 fix:     修復'   },   {     value: ':memo: docs',     name: '📝 docs:     文件變更'   },   {     value: ':lipstick: style', ​     name: '💄 style:     程式碼格式(不影響程式碼執行的變動)'   },   {     value: ':recycle: refactor', ​     name: '♻️ refactor:   重構 (既不增加feature, 也不是修復bug)'   },   {     value: ':zap: perf',     name: '⚡️ perf:     效能優化'   },   {     value: ':white_check_mark: test',     name: '✅ test:     增加測試'   },   {     value: ':wrench: chore',     name: '🔧 chore:     構建過程或輔助工具的變動'   },   {     value: ':rewind: revert',     name: '⏪ revert:     回退'   },   {     value: ':rocket: build',     name: '🚀 build:     打包'   } ], ​ // 步驟 ​ messages: {   type: '請選擇提交的型別：',   customScope: '情輸入修改的範圍(可選)',   subject: '請簡要描述提交(必填)',   body: '請輸入詳細描述(可選)',   footer: '請輸入要關閉的issus(可選)',   confirmCommit: '確認要使用以上資訊提交？(y/n)' }, // 預設長度72 subjectLimit: 72 }; ​

此時再次執行 git cz時就可以看到

? 請選擇提交的型別： (Use arrow keys) ❯ ✨ feat:     新功能 🐛 fix:     修復 📝 docs:     文件變更 💄 style:     程式碼格式(不影響程式碼執行的變動) ♻️ refactor:   重構 (既不增加feature, 也不是修復bug) ⚡️ perf:     效能優化 ✅ test:     增加測試

第三部： 增加對自動生成 commit 資訊的校驗

有時候你的隊友可能是傻逼？請你注意防範

很遺憾的是，上面的操作並沒有任何校驗功能，你的隊友仍然可以提交 trash 在 commit 資訊中。如果不敲你是隊伍中的稽核人員，那麼我想你需要設定一些規範

這裡我們分情況討論：

若您沒有使用cz-customizable介面卡做了破壞Angular風格的提交說明配置，則可以使用以下配置方案

1.安裝 @commitlint/config-conventional

npm i @commitlint/config-conventional @commitlint/cli -D

2.在根目錄建立commitlint.config.js檔案，配置commitlint

module.exports = {  extends: ['@commitlint/config-conventional'] }

若您使用cz-customizable了則需要使用以下配置方案

npm install commitlint-config-cz --save-dev 複製程式碼

然後加入commitlint校驗規則配置：

module.exports = { extends: [   'cz' ] };

最後的一些補充

husky 最後的幫手

是一個可以在 Git hooks 中使用的 npm 包，它可以幫助你在特定的 Git 事件發生時執行命令，例如提交程式碼之前進行程式碼格式化、測試等操作.

"husky"是一個為了方便使用Git hooks的工具，它能夠幫助你在專案中自動化地執行一些Git相關的操作。使用husky，你可以在Git的一些關鍵操作（例如提交、推送、合併等）前或後，執行一些指令碼或命令，比如程式碼格式化、自動化測試、打包釋出等。

他可以幫助我們額外攔截一些如git commit等指令。需要注意的是，husky只在Git倉庫中才能正常工作，所以在使用之前請確保你的專案已經初始化為Git倉庫

1.安裝 husky

  1. 在專案中安裝 husky，可以使用 npm或者 yarn 進行安裝：

pnpm install husky --save-dev

或者

yarn add husky --dev

2.在package.json中定義需要執行的Git hooks和對應的指令碼

例如，在提交程式碼前執行程式碼格式化和自動化測試：

jsonCopy code{ "husky": {   "hooks": {     "pre-commit": "npm run lint && npm run test"   } } }

這樣，每次在執行git commit命令時，都會自動執行npm中定義的lint和test命令。

除了pre-commit鉤子，husky還支援其他一些Git hooks，比如pre-push、post-merge、post-checkout等，可以根據實際需求進行配置。

需要注意的是，husky只在Git倉庫中才能正常工作，所以在使用之前請確保你的專案已經初始化為Git倉庫。

當然 除了在pageage.json中設定之外，還可以使用

npx husky add .husky/pre-commit來生成一個 hook 的檔案

隨後你也可以在相應的檔案中書寫要執行的指令碼了

./.husky/ ├── _ │   └── husky.sh ├── commit-msg └── pre-commit // 再此寫入

3.使用lint-staged, 對暫存區程式碼進行eslint校驗和prettier格式化

現在我們已經約束了提交規範，但是我們希望在提交前對當前的程式碼進行格式驗證和修復，此時需要使用到lint-staged

  1. 安裝 npm i lint-staged --save-dev

  2. 在package.json中新增配置

    "lint-staged": {  "**/*.scss": "stylelint --syntax scss",  "**/*.{js,jsx, tsx,ts }": "npm run lint-staged:js",  "**/*.{js,jsx,tsx,ts,less,scss,md,json}": [    "prettier --write" ] } 複製程式碼

  3. 在package.json中新增 lint-staged 和 lint-staged.js 命令

    "scripts": {    "lint-staged": "lint-staged",    "lint-staged:js": "eslint --ext .js,.jsx,.ts,.tsx " } 複製程式碼

  4. 最後在 pre-commit中新增指令碼

    npm run lint-staged

連結文件

[Cz工具集使用介紹 - 規範Git提交說明]  https://juejin.cn/post/6844903831893966856#heading-18 

[Commitizen約定式提交]  https://juejin.cn/post/7104104607009210382#heading-4 

[Commitizen + husky規範提交資訊​]  https://juejin.cn/post/7091206349597442056

「」