如何使用工具規(guī)范前端項目的commits與changelog技巧
前言
項目的 Changelog 文件作為記錄版本之間的差異和變更的主要“公示板”，主要用于傳達一些關(guān)鍵的變更和指南，是直接與使用者對話的一種形式，所以 changelog 文件的整潔、直觀一直是衡量一個項目質(zhì)量的重要指標。
而且在我們翻閱一些組件庫或者開源框架的 changelog 變動頁的時候，經(jīng)常看到一些項目的整齊、直觀、井井有條如下面示例。這樣的 log 日志必然不是手動排版出來的，大部分都是根據(jù) commit 的描述自動生成的。
那么它們是如何配置，或者使用了什么工具包呢？想必大家都比較好奇。接下來我們就來一步一步揭開它神秘的面紗，并一步步的配置我們的組件庫的 commit 規(guī)范，使我們的 commit 和 changelog 文件也能如此優(yōu)雅。
示例一：semi 的 changelog 文件
示例二：antd 的 github changelog
Conventional Commits 規(guī)范
要保持 commit 信息的可讀性，一個合理的 commit 格式規(guī)范是必不可少的，而 Conventional Commits 就是一種基于提交消息的輕量級約定。官方是這樣描述它的：
它提供了一組用于創(chuàng)建清晰的提交歷史的簡單規(guī)則； 這使得編寫基于規(guī)范的自動化工具變得更容易。 這個約定與SemVer相吻合， 在提交信息中描述新特性、bug 修復和破壞性變更。 --- Conventional Commits 官網(wǎng)
由此可以看出 Conventional Commits 是一個非常友好且清晰的規(guī)范，那遵循它的好處有哪些？ 我們來進行一個總結(jié)：
- 可格式化信息，自動產(chǎn)生 changelog；
- 校驗攔截不符合規(guī)則的 commit 描述；
- 根據(jù)類型決定當前版本變更的性質(zhì)；
- 統(tǒng)一提交信息，有利于代碼審查者的閱讀。
那么 Conventional Commits 規(guī)則到底是如何的呢，我們接著往下看。通過官網(wǎng)的文檔可以發(fā)現(xiàn)，它提交說明的結(jié)構(gòu)如下所示：
<類型>[可選的作用域]: <描述> [可選的正文] [可選的腳注] 舉例： fix(docs): 修復文檔中字符錯誤 feat(components): tooltip 組件初始化
可以看到，結(jié)構(gòu)里面包含類型、作用域、描述、正文、腳注。
- 類型：用來標示當前提交是一個什么樣的類型，比如最常見的有
fix、feat等，用來標示當前的提交是一個修復類的操作，或者一個新功能的增加。可枚舉的類型還有：chore、docs、style、refactor、perf、test等。這塊可以參照 @commitlint/config-conventional 里面的枚舉值。
- 作用域：此字段可自行定義枚舉值，根據(jù)業(yè)務(wù)模塊劃分即可，比如：當前是【文檔】的改動就可以填寫 docs；當前影響了 utils 庫，就可以填寫 feat(utils)：等等，取值不限制。
- 描述：描述就是對當前 commit 的簡短描述，盡量簡短，清晰。
對于簡短描述的擴充填寫，可選
- 腳注：包含關(guān)于提交的元信息，比如：有關(guān)聯(lián)的請求url、cr人員、等等一些關(guān)鍵性信息。
- 特別需要注意的是：在可選的正文或腳注的起始位置帶有
BREAKING CHANGE:的提交，表示引入了破壞性 API 變更（這和語義化版本中的MAJOR相對應(yīng)）。 破壞性變更可以是任意類型提交的一部分。
可以看出 Conventional Commits 規(guī)范非常高效且上手難度很低，并且 Conventional Commits 已經(jīng)被很多知名的開源項目所集成，是一個被大家廣泛接受的標準。而我們的組件庫也需要遵循它來規(guī)范我們的 commit。
要如何遵循此規(guī)范呢？用插件來約束我們的 commit 是一個比較好的解決方案。接下來，我們來看下有哪些插件可以讓我們愉快的使用。
哪些工具可以組合起來規(guī)范我們的 commit？
Commitizen
上面我們說到了 Conventional Commits 規(guī)范，我們要遵循此規(guī)范時，可能手動去處理 commit 信息會比較繁瑣，并且出錯率也很高，比如在我們書寫 fix(scope): xxx 時，很容易對于符合的全角還是半角輸入法搞混，這樣很容易造成信息格式化的失敗。那么我們該如何高效穩(wěn)定的遵循 Conventional Commits 規(guī)范呢？Commitizen 應(yīng)聲而來。
Commitizen 可以說是一個交互性日志提交工具，用于輔助開發(fā)者提交符合規(guī)范的 commit 信息。它可以說是提供了“保姆式”的提交體驗，在我們觸發(fā) commit 的腳本后，只需要根據(jù)提示來選擇我們的提交信息，就可以生成一個符合規(guī)范的 commit。
? Select the type of change that you're committing: (Use arrow keys) ? feat: A new feature fix: A bug fix docs: Documentation only changes style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) refactor: A code change that neither fixes a bug nor adds a feature perf: A code change that improves performance test: Adding missing tests or correcting existing tests (Move up and down to reveal more choices)
cz-customizable
cz-customizable 作為一個用于自定義 Commitizen 的擴展插件，可以在原生 Commitizen 的標準上，根據(jù)配置文件來自定義我們的提交規(guī)范。可以說是用來擴展 Commitizen 的神器。一般都用于 Commitizen 的配套使用。
? 選擇一種你的提交類型: (Use arrow keys) ? feat ??: 新增新的特性 fix ??: 修復 BUG docs ??: 修改文檔、注釋 refactor ??: 代碼重構(gòu)，注意和特性、修復區(qū)分開 perf ?: 提升性能 test ??: 添加一個測試 tool ??: 開發(fā)工具變動(構(gòu)建、腳手架工具等) (Move up and down to reveal more choices)
commitlint
commitlint 用來校驗檢查我們的提交 commit 是否符合conventional commit format。類似于 eslint，commitlint 可以根據(jù)我們的配置文件或者默認的選項值來校驗我們的 commit 信息，不通過的校驗會被直接打回。
standard-version
standard-version 是一款遵循語義化版本（semver）和 commit message 標準規(guī)范的版本自動化工具，它還可以使生成 changelog 自動化。并且將我們符合 Conventional Commits 規(guī)范的提交信息格式化，并完成以下操作：
- 根據(jù)現(xiàn)在 package.json 文件中的 版本號 version 進行 commit 的整合。并更新 changelog 文件。
- 提交暫存文件 git add . 。
- git commit 。
- 打標簽 git tag。
總體來說，它幫助我們自動化的進行了發(fā)版所需要的步驟，并且根據(jù) commit 信息，生成 log 日志。這樣我們就只需要專注于我們的邏輯開發(fā)，其他的都可以交給 standard-version 去完成。
以上是我們規(guī)范 commit 信息、根據(jù)提交的 commit 信息自動化更新 changelog、發(fā)版等一條龍服務(wù)所必須用到的插件。經(jīng)過簡單的熟悉后，我們來進行實際的配置，讓我們組件庫的 commit 優(yōu)美起來。
安裝配置
俗話說的好，動手是第一生產(chǎn)力。接下來我們將一步步安裝配置我們的 commit 規(guī)范。
1. 安裝 commitizen 和 cz-customizable
pnpm install -D commitizen cz-customizable
在最外層 package.json 文件中添加腳本命令和配置項，使 commitizen 使用cz-customizable 插件。
{
...
"scripts" : {
...
"commit": "git cz"
}
...
"config": {
"commitizen": {
"path": "cz-customizable"
}
}
}
接下來在根目錄新建 .cz-config.js 文件，并加入我們的漢化配置。
// .cz-config.js module.exports = {
types: [
{ value: "feat", name: "feat ??: 新增新的特性" },
{ value: "fix", name: "fix ??: 修復 BUG" },
{ value: "docs", name: "docs ??: 修改文檔、注釋" },
{ value: "refactor", name: "refactor ??: 代碼重構(gòu)，注意和特性、修復區(qū)分開" },
{ value: "perf", name: "perf ?: 提升性能" },
{ value: "test", name: "test ??: 添加一個測試" },
{ value: "tool", name: "tool ??: 開發(fā)工具變動(構(gòu)建、腳手架工具等)" },
{ value: "style", name: "style ?: 對代碼格式的修改不影響邏輯" },
{ value: "revert", name: "revert ??: 版本回滾" },
{ value: "update", name: "update ?: 第三方庫升級 " }
],
scopes: [{ name: '組件' }, { name: '樣式' }, { name: '文檔更改' }, { name: '其它變更' }],
allowTicketNumber: false,
isTicketNumberRequired: false,
ticketNumberPrefix: 'TICKET-',
ticketNumberRegExp: '\d{1,5}',
messages: {
type: "選擇一種你的提交類型:",
scope: "選擇一個scope (可選):",
customScope: "Denote the SCOPE of this change:",
subject: "簡要說明:\n",
body: '詳細說明，使用"|"換行(可選)：\n',
breaking: "非兼容性說明 (可選):\n",
footer: "關(guān)聯(lián)關(guān)閉的issue，例如：#31, #34(可選):\n",
confirmCommit: "確定提交?"
},
allowCustomScopes: true,
allowBreakingChanges: ['新增', '修復'], subjectLimit: 100 };
配置好后我們先進行測試：npm run commit ，得出下面結(jié)果：
All lines except first will be wrapped after 100 characters. ? 選擇一種你的提交類型: (Use arrow keys) ? feat ??: 新增新的特性 fix ??: 修復 BUG docs ??: 修改文檔、注釋 refactor ??: 代碼重構(gòu)，注意和特性、修復區(qū)分開 perf ?: 提升性能 test ??: 添加一個測試 tool ??: 開發(fā)工具變動(構(gòu)建、腳手架工具等)
說明配置完成，我們可以接著往下進行。
2. 安裝 commitlint
pnpm install -D commitlint-config-cz @commitlint/cli yorkie
在 package.json 中的 husky hook 中添加每次 commit 信息的校驗回調(diào)。
ps：沒有安裝 husky 的先自行安裝 pnpm install -D husky
{
"husky": {
"hooks": {
"commit-msg": "commitlint -e -V",
}
}
}
在根目錄構(gòu)建 commitlint.config.js 文件，進行 commitlint 的配置。
module.exports = {
extends: ['cz'],
parserPreset: {
parserOpts: {
headerPattern: /^(.*?)((.*?)):\s?(.*)$/,
headerCorrespondence: ['type', 'scope', 'subject'],
},
},
rules: {
'type-empty': [2, 'never'],
'subject-empty': [2, 'never'],
},
};
接下來我們實驗一下，提交一個空內(nèi)容。
? 選擇一種你的提交類型: feat ??: 新增新的特性 ? 選擇一個scope (可選): 其它變更 ? 簡要說明: ? sten-design git:(master) ? git commit -m 'feat' husky > commit-msg (node v14.17.0) ? input: feat ? type may not be empty [type-empty] ? subject may not be empty [subject-empty] ? found 2 problems, 0 warnings ? Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint husky > commit-msg hook failed (add --no-verify to bypass)
會報錯，說明我們的 commitlint 已經(jīng)生效。
3. 安裝 standard-version
pnpm install -D standard-version
配置腳本。
// package.json
{
"scripts": {
"release": "standard-version"
}
}
增加 .versionrc.js 文件來格式化 log ，使我們的 changelog 根據(jù) Conventional Commits 規(guī)范更加語義化。
module.exports = {
"types": [
{ "type": "feat", "section": "? Features | 新功能" },
{ "type": "fix", "section": "?? Bug Fixes | Bug 修復" },
{ "type": "init", "section": "?? Init | 初始化" },
{ "type": "docs", "section": "?? Documentation | 文檔" },
{ "type": "style", "section": "?? Styles | 風格" },
{ "type": "refactor", "section": "?? Code Refactoring | 代碼重構(gòu)" },
{ "type": "perf", "section": "? Performance Improvements | 性能優(yōu)化" },
{ "type": "test", "section": "? Tests | 測試" },
{ "type": "revert", "section": "? Revert | 回退" },
{ "type": "build", "section": "?? Build System | 打包構(gòu)建" },
{ "type": "update", "section": "?? update | 構(gòu)建/工程依賴/工具升級" },
{ "type": "tool", "section": "?? tool | 工具升級" },
{ "type": "ci", "section": "?? Continuous Integration | CI 配置" }
]
}
先提交一個 commit 再測試：
然后我們再執(zhí)行 yarn release 升級版本：
yarn run v1.22.11 $ standard-version ? bumping version in package.json from 0.0.1 to 0.0.2 ? created CHANGELOG.md ? outputting changes to CHANGELOG.md ? committing package.json and CHANGELOG.md husky > commit-msg (node v14.17.0) ? input: chore(release): 0.0.2 ? found 0 problems, 0 warnings ? tagging release v0.0.2 ? Run `git push --follow-tags origin master` to publish ? Done in 2.79s.
我們再看下 CHANGELOG.md 文件：
# Changelog All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. ### [0.1.1]( https://github.com/fanshyiis/sten-design/compare/v0.0.8...v0.1.1) (2022-02-12) ### ?? tool | 工具升級 * **其它變更:** 測試 commit 信息 ([6446270](https://github.com/fanshyiis/sten-design/commit/64462708008fa863abcfc026191fe20499f586f8)) ### ? Features | 新功能 * **組件:** 我是一個新功能 ([9b9d30f](https://github.com/fanshyiis/sten-design/commit/9b9d30f7bac36b9b8c6e4786be45031cea6bfba6))
和具體 Git 上展示效果：
總結(jié)
在 Conventional Commits 和一系列組件的約束下，可以使我們的 changelog 文件更加直觀、優(yōu)美。并且，全自動化的配置，也不需要我們過多的關(guān)注，只需要用心寫好每一個 commit 的描述信息即可。
以上就是如何使用工具規(guī)范前端項目的commits與changelog技巧的詳細內(nèi)容，更多關(guān)于前端項目commits changelog規(guī)范的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
這篇文章主要為大家詳細介紹了JavaScript SHA512加密算法代碼，具有一定的參考價值，感興趣的朋友可以參考一下2016-10-10
改進：論壇UBB代碼自動插入方式...2006-12-12
下面小編就為大家分享一篇webpack 單獨打包指定JS文件的方法，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2018-02-02
javascript中通過arguments參數(shù)偽裝方法重載
面向?qū)ο蟮母呒壵Z言中，都有方法的重載，在js中可以通過arguments這個參數(shù)來偽裝成函數(shù)重載，具體如下2014-10-10
對于搶紅包來說最重要的就是隨機性算法,如何確保每個人獲得金額是趨向于平均的,也就是有平均的概率去隨機,而盡量避免兩極分化,本文給大家介紹了用JS實現(xiàn)搶紅包的三種算法,文中有相關(guān)的代碼示例,需要的朋友可以參考下2024-03-03
bootstrap配合Masonry插件實現(xiàn)瀑布式布局
這篇文章主要為大家詳細介紹了bootstrap配合Masonry插件實現(xiàn)瀑布式布局，具有一定的參考價值，感興趣的小伙伴們可以參考一下2017-01-01
document.execCommand()的用法小結(jié)
本篇文章主要是對document.execCommand()的用法進行了詳細的介紹，需要的朋友可以過來參考下，希望對大家有所幫助2014-01-01
js獲取參數(shù)的具體應(yīng)用，歡迎加入腳本之家交流群2007-12-12
下面小編就為大家?guī)硪黄唵畏庋bjs的dom查詢實例代碼。小編覺得挺不錯的，現(xiàn)在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2016-07-07
這篇文章主要為大家詳細介紹了用js實現(xiàn)簡單的tab選項卡，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下2021-09-09