官網(wǎng)：https://www.conventionalcommits.org/
約定式提交 1.0.0
概述
約定式提交規(guī)范是一種基于提交信息的輕量級(jí)約定。
它提供了一組簡單規(guī)則來創(chuàng)建清晰的提交歷史；
這更有利于編寫自動(dòng)化工具。
通過在提交信息中描述功能、修復(fù)和破壞性變更，
使這種慣例與 SemVer 相互對(duì)應(yīng)。
提交說明的結(jié)構(gòu)如下所示：
原文：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
譯文：
<類型>[可選 范圍]: <描述>
[可選 正文]
[可選 腳注]
<br />
提交說明包含了下面的結(jié)構(gòu)化元素，以向類庫使用者表明其意圖：
-
fix: 類型 為
fix的提交表示在代碼庫中修復(fù)了一個(gè) bug（這和語義化版本中的PATCH相對(duì)應(yīng)）。 -
feat: 類型 為
feat的提交表示在代碼庫中新增了一個(gè)功能（這和語義化版本中的MINOR相對(duì)應(yīng)）。 -
BREAKING CHANGE: 在腳注中包含
BREAKING CHANGE:或 <類型>(范圍) 后面有一個(gè)!的提交，表示引入了破壞性 API 變更（這和語義化版本中的MAJOR相對(duì)應(yīng)）。
破壞性變更可以是任意 類型 提交的一部分。 - 除
fix:和feat:之外，也可以使用其它提交 類型 ，例如 @commitlint/config-conventional（基于 Angular 約定）中推薦的build:、chore:、
ci:、docs:、style:、refactor:、perf:、test:，等等。 - 腳注中除了
BREAKING CHANGE: <description>，其它條目應(yīng)該采用類似
git trailer format 這樣的慣例。
其它提交類型在約定式提交規(guī)范中并沒有強(qiáng)制限制，并且在語義化版本中沒有隱式影響（除非它們包含 BREAKING CHANGE）。
<br /><br />
可以為提交類型添加一個(gè)圍在圓括號(hào)內(nèi)的范圍，以為其提供額外的上下文信息。例如 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
包含了 ! 字符以提醒注意破壞性變更的提交說明
refactor!: drop support for Node 6
包含了 ! 和 BREAKING CHANGE 腳注的提交說明
refactor!: drop support for Node 6
BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.
不包含正文的提交說明
docs: correct spelling of CHANGELOG
包含范圍的提交說明
feat(lang): add polish language
包含多行正文和多行腳注的提交說明
fix: correct minor typos in code
see the issue for details
on typos fixed.
Reviewed-by: Z
Refs #133
約定式提交規(guī)范
本文中的關(guān)鍵詞 “必須（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“應(yīng)當(dāng)（SHALL）”、“不應(yīng)當(dāng)（SHALL NOT）”、“應(yīng)該（SHOULD）”、“不應(yīng)該（SHOULD NOT）”、“推薦（RECOMMENDED）”、“可以（MAY）” 和 “可選（OPTIONAL）” ，其相關(guān)解釋參考 RFC 2119 。
- 每個(gè)提交都必須使用類型字段前綴，它由一個(gè)名詞構(gòu)成，諸如
feat或fix，
其后接可選的范圍字段，可選的!，以及必要的冒號(hào)（英文半角）和空格。 - 當(dāng)一個(gè)提交為應(yīng)用或類庫實(shí)現(xiàn)了新功能時(shí)，必須使用
feat類型。 - 當(dāng)一個(gè)提交為應(yīng)用修復(fù)了 bug 時(shí)，必須使用
fix類型。 - 范圍字段可以跟隨在類型字段后面。范圍必須是一個(gè)描述某部分代碼的名詞，并用圓括號(hào)包圍，例如：
fix(parser): - 描述字段必須直接跟在 <類型>(范圍) 前綴的冒號(hào)和空格之后。
描述指的是對(duì)代碼變更的簡短總結(jié)，例如： fix: array parsing issue when multiple spaces were contained in string 。 - 在簡短描述之后，可以編寫較長的提交正文，為代碼變更提供額外的上下文信息。正文必須起始于描述字段結(jié)束的一個(gè)空行后。
- 提交的正文內(nèi)容自由編寫，并可以使用空行分隔不同段落。
- 在正文結(jié)束的一個(gè)空行之后，可以編寫一行或多行腳注。每行腳注都必須包含
一個(gè)令牌（token），后面緊跟:<space>或<space>#作為分隔符，后面再緊跟令牌的值（受
git trailer convention 啟發(fā)）。 - 腳注的令牌必須使用
-作為連字符，比如Acked-by(這樣有助于
區(qū)分腳注和多行正文)。有一種例外情況就是BREAKING CHANGE，它可以被認(rèn)為是一個(gè)令牌。 - 腳注的值可以包含空格和換行，值的解析過程必須直到下一個(gè)腳注的令牌/分隔符出現(xiàn)為止。
- 破壞性變更必須在提交信息中標(biāo)記出來，要么在 <類型>(范圍) 前綴中標(biāo)記，要么作為腳注的一項(xiàng)。
- 包含在腳注中時(shí)，破壞性變更必須包含大寫的文本
BREAKING CHANGE，后面緊跟著冒號(hào)、空格，然后是描述，例如：
BREAKING CHANGE: environment variables now take precedence over config files 。 - 包含在 <類型>(范圍) 前綴時(shí)，破壞性變更必須通過把
!直接放在:前面標(biāo)記出來。
如果使用了!，那么腳注中可以不寫BREAKING CHANGE:，
同時(shí)提交信息的描述中應(yīng)該用來描述破壞性變更。 - 在提交說明中，可以使用
feat和fix之外的類型，比如：docs: updated ref docs. 。 - 工具的實(shí)現(xiàn)必須不區(qū)分大小寫地解析構(gòu)成約定式提交的信息單元，只有
BREAKING CHANGE必須是大寫的。 - BREAKING-CHANGE 作為腳注的令牌時(shí)必須是 BREAKING CHANGE 的同義詞。
為什么使用約定式提交
- 自動(dòng)化生成 CHANGELOG。
- 基于提交的類型，自動(dòng)決定語義化的版本變更。
- 向同事、公眾與其他利益關(guān)系者傳達(dá)變化的性質(zhì)。
- 觸發(fā)構(gòu)建和部署流程。
- 讓人們探索一個(gè)更加結(jié)構(gòu)化的提交歷史，以便降低對(duì)你的項(xiàng)目做出貢獻(xiàn)的難度。
FAQ
在初始開發(fā)階段我該如何處理提交說明？
我們建議你按照假設(shè)你已發(fā)布了產(chǎn)品那樣來處理。因?yàn)橥ǔ？?有人 使用你的軟件，即便那是你軟件開發(fā)的同事們。他們會(huì)希望知道諸如修復(fù)了什么、哪里不兼容等信息。
提交標(biāo)題中的類型是大寫還是小寫?
大小寫都可以，但最好是一致的。
如果提交符合多種類型我該如何操作？
回退并盡可能創(chuàng)建多次提交。約定式提交的好處之一是能夠促使我們做出更有組織的提交和 PR。
這不會(huì)阻礙快速開發(fā)和迭代嗎？
它阻礙的是以雜亂無章的方式快速前進(jìn)。它助你能在橫跨多個(gè)項(xiàng)目以及和多個(gè)貢獻(xiàn)者協(xié)作時(shí)長期地快速演進(jìn)。
約定式提交會(huì)讓開發(fā)者受限于提交的類型嗎（因?yàn)樗麄儠?huì)想著已提供的類型）？
約定式提交鼓勵(lì)我們更多地使用某些類型的提交，比如 fixes。除此之外，約定式提交的靈活性也允許你的團(tuán)隊(duì)使用自己的類型，并隨著時(shí)間的推移更改這些類型。
這和 SemVer 有什么關(guān)聯(lián)呢？
fix 類型提交應(yīng)當(dāng)對(duì)應(yīng)到 PATCH 版本。feat 類型提交應(yīng)該對(duì)應(yīng)到 MINOR 版本。帶有 BREAKING CHANGE 的提交不管類型如何，都應(yīng)該對(duì)應(yīng)到 MAJOR 版本。
我對(duì)約定式提交做了形如 @jameswomack/conventional-commit-spec 的擴(kuò)展，該如何版本化管理這些擴(kuò)展呢？
我們推薦使用 SemVer 來發(fā)布你對(duì)于這個(gè)規(guī)范的擴(kuò)展（并鼓勵(lì)你創(chuàng)建這些擴(kuò)展?。?/p>
如果我不小心使用了錯(cuò)誤的提交類型，該怎么辦呢？
當(dāng)你使用了在規(guī)范中但錯(cuò)誤的類型時(shí)，例如將 feat 寫成了 fix
在合并或發(fā)布這個(gè)錯(cuò)誤之前，我們建議使用 git rebase -i 來編輯提交歷史。而在發(fā)布之后，根據(jù)你使用的工具和流程不同，會(huì)有不同的清理方案。
當(dāng)使用了 不在 規(guī)范中的類型時(shí)，例如將 feat 寫成了 feet
在最壞的場景下，即便提交沒有滿足約定式提交的規(guī)范，也不會(huì)是世界末日。這只意味著這個(gè)提交會(huì)被基于規(guī)范的工具錯(cuò)過而已。
所有的貢獻(xiàn)者都需要使用約定式提交規(guī)范嗎？
并不！如果你使用基于 squash 的 Git 工作流，主管維護(hù)者可以在合并時(shí)清理提交信息——這不會(huì)對(duì)普通提交者產(chǎn)生額外的負(fù)擔(dān)。
有種常見的工作流是讓 git 系統(tǒng)自動(dòng)從 pull request 中 squash 出提交，并向主管維護(hù)者提供一份表單，用以在合并時(shí)輸入合適的 git 提交信息。
約定式提交規(guī)范中如何處理還原（revert）提交?
還原提交（Reverting）會(huì)比較復(fù)雜：你還原的是多個(gè)提交嗎？如果你還原了一個(gè)功能模塊，下次發(fā)布的應(yīng)該是補(bǔ)丁嗎？
約定式提交不能明確的定義還原行為。所以我們把這個(gè)問題留給工具開發(fā)者，
基于 類型 和 腳注 的靈活性來開發(fā)他們自己的還原處理邏輯。
一種建議是使用 revert 類型，和一個(gè)指向被還原提交摘要的腳注：
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
關(guān)于
約定式提交規(guī)范受到了 Angular 提交準(zhǔn)則的啟發(fā)，并在很大程度上以其為依據(jù)。
該規(guī)范的首個(gè)草案來自下面這些項(xiàng)目中若干貢獻(xiàn)者們的協(xié)作：
- conventional-changelog：一套從 git 歷史中解析出約定式提交說明的工具。
- parse-commit-message：用于轉(zhuǎn)換、字符串化、校驗(yàn)約定式提交信息的擴(kuò)展工具。
- bumped：一個(gè)用于發(fā)布軟件的工具，可以在為你的軟件發(fā)布新版本前后輕松地執(zhí)行操作。
- unleash：一個(gè)用于自動(dòng)化軟件發(fā)行和發(fā)布生命周期的工具。
- lerna：一個(gè)用于管理宏倉庫（monorepo）的工具，源自 Babel 項(xiàng)目。
用于約定式提交的工具
- fastlane-plugin: 根據(jù)規(guī)范管理版本并自動(dòng)生成變更日志。
- commitizen/cz-cli: Node.js 工具，用于創(chuàng)建遵循約定式提交規(guī)范的提交信息。
- commitizen-tools/commitizen: Python 編寫的項(xiàng)目提交規(guī)則創(chuàng)建工具，自動(dòng)增加版本號(hào)并生成變更記錄。
-
php-commitizen: PHP工具，用于創(chuàng)建遵循約定式提交規(guī)范的提交信息。
可配置，并且可以作為 composer 依賴項(xiàng)用于 PHP 項(xiàng)目，或可在非 PHP 項(xiàng)目中全局使用。 - commitlint: 用于檢查提交信息是否符合約定式提交規(guī)范的檢查器。
- gitlint: Python 開發(fā)的 Git 提交信息檢查器，可以通過 enforce Conventional Commits format 進(jìn)行配置。
- conform: 一個(gè)可用以在 git 倉庫上施加配置的工具，包括約定式提交。
- detect-next-version: 對(duì)約定式提交規(guī)范的內(nèi)容進(jìn)行解析、檢測并提取出元信息。
- recommended-bump: 根據(jù)約定式提交的信息計(jì)算并推薦新版本號(hào)。
- git-commits-since: 獲取一個(gè)周期內(nèi)或上一個(gè)語義化版本到現(xiàn)在的所有原始提交信息，支持自定義插件。
- standard-version: 自動(dòng)化的版本和 CHANGELOG 管理。使用 GitHub 新的合并提交按鈕，并推薦使用約定式提交工作流。
- Conventional Commit: 在版本控制系統(tǒng)的提交窗口中提供可擴(kuò)展的約定式提交規(guī)范模板，可以用于所有 JetBrains IDEs。
- Git Commit Template: 在 JetBrains Editors (IntelliJ IDEA, PyCharm, PhpStorm...) 中增加約定式提交規(guī)范的支持。
- commitsar: Go 工具，用于檢查分支上的提交信息是否符合約定式提交規(guī)范，并提供了 Docker 鏡像給 CI 用戶使用。
- semantic-release: 一個(gè)自動(dòng)化整個(gè)項(xiàng)目的工具，包括：決定下一個(gè)版本號(hào)，生成發(fā)布說明并發(fā)布項(xiàng)目包。
- python-semantic-release: 為 Python 項(xiàng)目提供自動(dòng)化語義版本。這是一個(gè) Python 版本的 semantic-release。
- VSCode Conventional Commits: 為 VSCode 添加約定式提交規(guī)范的支持。
- Pyhist: Python 工具，根據(jù) git 歷史記錄自動(dòng)更新包版本并生成變更日志。
- git-mkver: 根據(jù) Conventional Commits 在 git 項(xiàng)目中自動(dòng)實(shí)現(xiàn)語義化版本的工具。
- Conventional Commits Next Version: 跨語言工具，從最近的一個(gè)版本開始，根據(jù)符合 Conventional Commits 的提交信息，計(jì)算下一個(gè)語義化版本。
使用約定式提交的項(xiàng)目
- yargs：廣受歡迎的命令行參數(shù)解析器。
- istanbuljs：一套為 JavaScript 測試生成測試覆蓋率的開源工具和類庫。
- uPortal-home 和 uPortal-application-framework：用于增強(qiáng) Apereo uPortal 的可選用戶界面。
- massive.js：一個(gè)用于 Node 和 PostgreSQL 的數(shù)據(jù)訪問類庫。
- electron：用 JavaScript、HTML 和 CSS 構(gòu)建跨平臺(tái)應(yīng)用。
- scroll-utility：一個(gè)居中元素和平滑動(dòng)畫的滾屏工具包實(shí)例。
- Blaze UI：無框架開源 UI 套件。
- Monica：一個(gè)開源的人際關(guān)系管理系統(tǒng)。
- mhy：一個(gè)零配置、開箱即用的、多用途工具箱與開發(fā)環(huán)境。
- @tandil/diffparse: 簡單的 Diff 文件解析器（統(tǒng)一 diff 格式）。
- @tandil/diffsplit: 快速將 .diff 和 .patch 拆分成獨(dú)立文件。
- @thi.ng/umbrella: 數(shù)據(jù)驅(qū)動(dòng)開發(fā)的 ~100 個(gè) TypeScript 項(xiàng)目。
- yii2-basic-firestarter: ?? Yii2應(yīng)用的增強(qiáng)模板。
- dcyou/resume: ?? 快速創(chuàng)建在線簡歷的模板。
- Nintex Forms: 方便的創(chuàng)建動(dòng)態(tài)在線表單并獲準(zhǔn)確、實(shí)時(shí)數(shù)據(jù)。
- Tina CMS: 為你的網(wǎng)站創(chuàng)建前端內(nèi)容管理的開源工具集。
- Uno Platform: 使用 C# 和 XAML 創(chuàng)建移動(dòng)、桌面和 WebAssembly 應(yīng)用。今天，開源并給予專業(yè)支持。
[圖片上傳失敗...(image-31f075-1605002713878)]
想讓你的項(xiàng)目出現(xiàn)在上面嗎？ 提交 pull request 吧。
