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