文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载慣例式提交Conventional Commits是一套作用於 Git 提交說明的輕量級慣例它用簡單的規則集合建立明確、可讀且可被機器解析的提交歷史並與語意化版本SemVer一一對應feat對應次版本MINOR、fix對應修訂號PATCH、BREAKING CHANGE對應主版本MAJOR。本指南以本倉庫conventionalcommits.org即慣例式提交規範的官方開源倉庫中 content/v1.0.0/index.zh-hant.md1.0.0 正式版繁體中文翻譯為主體完整覆蓋提交訊息的結構、類型體系、作用範圍、頁腳footer慣例、RFC 2119 規範全文、官方範例與 FAQ並結合倉庫的目錄結構、多語言配置與本地建置方式讓你能在團隊中直接落地這套規範。概述什麼是慣例式提交慣例式提交規範是一種對提交說明的輕量慣例。它提供一些簡單的條件集合用於建立明確的提交歷史這能讓自動化工具更容易撰寫。這份慣例能對應到 SemVer透過在提交說明裡描述功能、修正以及重大變更。其核心思想是提交說明不只是寫給人看的備註更是機器可讀的「版本演進訊號」。提交說明中描述的「功能、修正、重大變更」三類資訊正是決定下一個發行版號該如何變動的依據。因此在 1.0.0 正式版中規範明確規定提交說明必須依照以下結構建構類型 type[可選的作用範圍 scope]: 描述 description [可選的正文 body] [可選的頁腳 footer]提交應包含以下結構性元素用以向使用這套函式庫的使用者溝通當時的意圖fix:為fix類型的提交表示對程式修正了一個臭蟲bug對應到語意化版本中的修訂號 PATCH。feat:為feat類型的提交表示對程式增加了一個功能對應到語意化版本中的次版本 MINOR。BREAKING CHANGE:重大變更如果提交的頁腳以BREAKING CHANGE:開頭或是在類型、作用範圍後有!代表包含了重大 API 變更對應到語意化版本中的主版本 MAJOR。重大變更可以是任何類型提交的一部分。其他: 除fix:與feat:以外其他的提交類型也是被允許的例如 commitlint/config-conventional基於 Angular 慣例中推薦的chore:、docs:、style:、refactor:、perf:、test:以及更多。我們也推薦對那些沒有增加新功能或是修正臭蟲而是改善目前實作的提交使用improvement。請注意這些類型在慣例式提交規範中並不是強制性的且在語意化版本中也沒有隱含的作用除非它們包含 BREAKING CHANGE。除了fix:與feat:之外也允許其他的類型如基於 Angular 慣例的commitlint/config-conventional 推薦使用build:與chore:、ci:、docs:、style:、refactor:、perf:、test:、等其他。也可以使用BREAKING CHANGE: 描述之外的頁腳並遵守類似 git trailer formatgit interpret-trailers 慣例的慣例。追加類型並不被慣例式提交所束縛並且不對語義化版本有任何隱藏的影響但若包含 BREAKING CHANGE 則不在此限。提交的類型可以在括號內給予作用範圍以提供額外的脈絡資訊。例如feat(parser): add ability to parse arrays。與 SemVer 的對應關係慣例式提交與語意化版本SemVer的對應是這份規範最具實用價值的部分也是自動化版本號升級工具的運作基礎提交特徵SemVer 版本號變動對應段落fix:類型修訂號PATCH如1.0.0 → 1.0.1修正臭蟲feat:類型次版本MINOR如1.0.1 → 1.1.0新增功能含BREAKING CHANGE:或!主版本MAJOR如1.1.0 → 2.0.0破壞性 API 變更從倉庫中可以進一步印證這套對應邏輯的「歷史演進」在較早期的 content/v1.0.0-beta.4/index.md 中!必須與BREAKING CHANGE: description頁腳同時出現而在 1.0.0 正式版本篇文章的主體中兩者被放寬為二選一的等價表達方式見下方規範第 13 條。完整範例解析規範原文提供了 7 組代表性範例覆蓋了從最簡潔到最完整的提交說明形態。以下逐一解析。1. 包含描述以及頁腳有重大變更的提交說明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類型 正文後空一行 BREAKING CHANGE:頁腳。頁腳中的描述說明了 API 行為的變化點extends鍵的語義從「合併」改為「擴充」這正是工具需要寫進 changelog 與 MAJOR 版本說明書的內容。2. 包含用以提示重大變更的!的提交說明feat!: send an email to the customer when a product is shipped!緊鄰在冒號之前、位於類型之後是 1.0.0 規範引入的前綴式重大變更標記。此例中沒有BREAKING CHANGE:頁腳——根據規範第 13 條使用!後可省略頁腳此時提交說明本身描述即應用來描述重大變更。3. 包含作用範圍和提示重大變更的!的提交說明feat(api)!: send an email to the customer when a product is shipped作用範圍scope置於括號內、位於!之前完整的前綴順序是類型(作用範圍)!:。api表示這次變更影響的是 API 層面為讀者與工具提供了額外的上下文。4. 包含!以及頁腳有重大變更的提交說明feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.此例同時使用了!前綴與BREAKING CHANGE:頁腳屬於最「明顯」的重大變更宣告前綴吸引注意力頁腳給出完整描述。這是合法的寫法頁腳可選也常用於希望雙重強調的場合。5. 不包含正文的提交說明docs: correct spelling of CHANGELOG最簡潔的提交只有類型 描述沒有作用範圍、正文與頁腳。docs類型表示純文件變更對 SemVer 版本號沒有影響。6. 包含作用範圍的提交說明feat(lang): add polish languagelang作用範圍指明功能變更位於「語言支援」這塊程式區段適用於大型 codebase 中定位改動位置。7. 正文有多段落以及有多個頁腳的提交說明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這是最完整的提交形態示範了三點關鍵規則正文由多個以換行分隔的段落組成用來說明問題成因racing 請求與解決方案request id 最新請求參照多個頁腳依次列出Reviewed-by: Z審閱者與Refs: #123關聯 issue/PR 編號頁腳符記tokenReviewed-by以-取代空白Refs使用space#分隔符後接#123——這正是源自 git trailer 慣例的格式:space或space#。規範全文RFC 2119 關鍵字解釋規範本文中使用的關鍵字MUST、MUST NOT、REQUIRED、SHALL、SHALL NOT、SHOULD、SHOULD NOT、RECOMMENDED、MAY、以及 OPTIONAL均以 RFC 2119 為參考解釋。也就是說MUST是強制要求、MAY是可選、SHOULD是建議這決定了某條規則「違反」時的嚴重程度。以下為 1.0.0 規範的 16 條規則全文每個提交最前面「必須 MUST」要有類型類型由名詞組成例如feat、fix等後接上「可選的 OPTIONAL」作用範圍以及「必要的 REQUIRED」一個冒號與空格。當提交一個新功能到你的應用程式或是函式庫時「必須 MUST」使用feat類型。當提交一個臭蟲修正到你的應用程式時「必須 MUST」使用fix類型。類型之後「可以 MAY」加上作用範圍。個別作用範圍「必須 MUST」由一個描述程式區段的名詞所組成並用括號包覆。例如fix(parser):。描述「必須 MUST」緊鄰在類型作用範圍後的冒號與空格。描述是對於程式碼修改的簡短總結如fix: array parsing issue when multiple spaces were contained in string。在簡短的描述後「可以 MAY」加上更長的提交正文提供關於對程式碼變更的額外脈絡資訊。正文「必須 MUST」在描述後的一個空行之後開始。提交正文為自由格式並「可以 MAY」有數個以換行字元區分的段落。在正文後「可以 MAY」有一個或多個頁腳頁腳在正文後空行之後開始。每個頁腳「必須 MUST」包含一個符記token並接著以:space或space#分隔再緊鄰一個字串值。本處靈感係源自於 git trailer convention。頁腳的符記「必須 MUST」使用-作為空白字元如Acked-by這有助於區分出頁腳與多段落的正文。但BREAKING CHANGE則為例外且也「可以 MAY」作為符記使用。頁腳的值「可以 MAY」包含空白與換行解析時「必須 MUST」在遇到下一組有效的符記分隔時停止。重大變更「必須 MUST」作為提交中的類型作用範圍的前綴或是在頁腳中作為一個段落存在。若放置於頁腳重大變更「必須 MUST」維持大寫文字BREAKING CHANGE而後緊鄰一個分號、空白、並接著描述。如BREAKING CHANGE: environment variables now take precedence over config files。若作為類型作用範圍的前綴重大變更「必須 MUST」以一個!識別並緊鄰於:之前。若使用!頁腳段落的BREAKING CHANGE:則「可以 MAY」被省略且提交說明「應當 SHALL」用來描述重大變更。除了feat與fix以外的類型「可以 MAY」被用於提交訊息內如docs: updated ref docs。組成慣例式提交資訊的單位在實作時除了大寫的BREAKING CHANGE外「禁止 MUST NOT」區分大小寫。在作為頁腳符記時BREAKING-CHANGE「必須 MUST」與BREAKING CHANGE視為相同的。規範條文的解析重點第 1 條前綴結構強制的只有「類型 冒號 空格」三件套作用範圍與!都是可選的。feat:、fix:都是合法前綴feat(parser):、feat(api)!:也是。第 5 條描述描述必須緊接在冒號與空格之後中間不能再插入其他內容且應是簡短總結——這決定了提交標題第一行的可讀性。第 810 條頁腳語法這是機器解析最容易出錯的部分。頁腳符記與值之間必須是:space或space#符記內部用-取代空白以與多段落正文區分多個頁腳值解析到「下一個有效符記分隔」時停止——這保證了多頁腳與跨行值的正確解析。第 1113 條重大變更的兩種宣告方式前綴式!與頁腳式BREAKING CHANGE:是等價且可省略其一第 16 條進一步規定BREAKING-CHANGE連字號作為頁腳符記時與BREAKING CHANGE同義兼顧了不同書寫習慣的工具相容性。第 15 條大小寫除BREAKING CHANGE外實作者在解析時不得區分大小寫例如Feat與feat應被同等對待但BREAKING CHANGE必須大寫第 12 條。從實作角度看這些規則直接決定了解析器parser的行為例如頁腳符記的-規則、BREAKING-CHANGE同義規則、大小寫不敏感規則都是 content/next/index.md 中提及的 go-conventionalcommits、commitlint、standard-version 等工具必須遵守的解析細節。為何要使用慣例式提交規範原文給出了採用這套慣例的五個直接收益自動產生修改日誌Changelog。基於提交的類型自動決定語意化版本的升級。向同事、公眾以及其他的利益相關者傳達變化的過程。觸發建置與發布流程。讓大家探索更有結構的提交歷史使你的專案更容易被貢獻。第五點尤其關鍵結構化提交歷史本身就是開源專案的「貢獻門檻降低器」——新貢獻者可以從提交歷史中快速理解專案的演進脈絡而維護者可以依賴工具自動生成 release notes。FAQ常見問題與官方解答規範 FAQ 部分針對實務中最高頻的問題給出權威解答以下完整收錄。在初始的開發階段我該如何處理提交說明我們建議你可以就像是產品已經發行的那樣去執行。因為通常都會有人使用你的軟體即使是你的軟體開發的同事們他們會希望知道修正了什麼以及有什麼重大變更等資訊。提交標題中的類型應該要用大寫還是小寫大小寫都可以但是最好是一致的。對應規範第 15 條實作工具不得區分大小寫但團隊內部保持一致仍是最佳實踐。當提交符合一或多種提交類型我應該怎麼做退回並盡可能切成多個提交。慣例式提交的一個好處就是它能夠促使我們做更有組織的提交與拉取請求PR, Pull Request。這不會阻礙快速開發與快速迭代嗎它阻礙用非組織化的方式快速前進。它幫助你長期能在橫跨多個專案與多個貢獻者協作時都能快速前進。慣例式提交會讓開發者受限於提交的類型因為他們會用已提供的類型去思考嗎慣例式提交鼓勵我們多使用某些類型的提交例如fixes。除此之外慣例式提交的彈性也允許你的團隊使用自己的類型以及隨時間推移更改這些類型。這與 SemVer 有什麼關係呢fix類型的提交應該對應到PATCH發行版。feat類型的提交應該對應到MINOR發行版。含有BREAKING CHANGE的提交無論是什麼類型都應該要對應到MAJOR發行版。我對慣例式提交做了擴充例如jameswomack/conventional-commit-spec我該如何管理這些擴充的版本呢我們推薦使用 SemVer 來發行你對這份規範的擴充並且也鼓勵你做些擴充如果我不小心用錯提交類型該怎麼辦當你使用規範中但是錯誤的類型例如將feat寫成fix在合併或是發行這個錯誤之前我們推薦使用git rebase -i來編輯提交歷史。而在發行之後根據你使用的工具與流程會有不同的清理方式。當你使用非規範中的類型時例如將feat寫成feet最糟狀況下即使提交沒有符合慣例式提交的規範也不會是世界末日。它僅意味著這個提交將會被基於這個規範的工具略過不會被計入版本號計算與 changelog 生成。所有的貢獻者都需要使用慣例式提交的規範嗎不用如果你使用的是基於 squash 的 Git 工作流程主維護者可以在合併時清理提交說明因此這不會對一般的提交者產生額外的負擔。有一種常見的工作流程是讓 git 系統自動從 pull request 中 squash 出提交然後提供一份表單給主維護者用以在合併的時候輸入合適的 git 提交說明。慣例式提交要如何處理回退提交revert commit回退程式碼可能非常複雜你是回退了多個提交嗎如果你回退了一個功能那麼下一個發行版應該要是修正檔嗎慣例式提交沒有強制定義回退的行為。反而我們將這個問題留給工具的作者靈活運用類型以及頁腳來開發處理回退的邏輯。其中一個推薦的方法時使用revert類型並在頁腳中參照到被回退的 SHA 雜湊revert: let us never again speak of the noodle incident Refs: 676104e, a215868這個範例同時示範了「自訂類型revert」與「頁腳參照Refs: SHA」的組合用法——兩者都是規範明確允許的彈性空間。在官方倉庫中的落地方式conventionalcommits.org 這個倉庫本身就是這份規範的「活樣本」它以 HUGO 靜態站生成器維護規範網站並採用**「一版本一目錄、多語言平行翻譯」**的組織方式。如果你想查看最新草案與版本演進以下倉庫位置可以直接參考content/v1.0.0/1.0.0 正式版收錄英文原文 index.md 與 20 種語言翻譯含本篇主體 index.zh-hant.md 繁體中文版、index.zh-hans.md 簡體中文版。content/next/index.md規範的下一版草案draft: true其中已經出現!!與INITIAL STABLE RELEASE等 1.0.0 尚未收錄的新概念適合追蹤規範未來的演進方向。content/v1.0.0-beta.4/index.md等 beta 目錄保留了 1.0.0 之前各草稿版本的歷史面貌可以用來對比!語法、頁腳規則的放寬過程。config.yaml站點的多語言配置。其中zh-hant區塊定義了繁體中文的languageName: 繁體中文、title: 慣例式提交、description一種用於增加提交說明之人機可讀性意義的規範以及versionscurrent: v1.0.0 與歷史版本列表——這也解釋了規範網站如何同時呈現多個版本。README.md說明倉庫佈局——./content存放規範所有版本./content/**/index.[lang].md是語言翻譯的存放規則並提供新增翻譯的流程用hugo new [version]/index.[lang].md建立文件後在 config.yaml 中加入對應語言。themes/conventional-commits/layouts/_default/single.html規範內容的渲染模板將 Markdown 內容經由{{.Content}}輸出為帶有 markdown-body 樣式的頁面並搭配 welcome 區塊展示版本徽章。如果你想在本地預覽這份規範的網站效果倉庫提供了 docker-compose.yml在安裝 docker-compose 後執行docker-compose up編譯完成即可訪問http://localhost:1313查看詳見 README.md 的「Running project locally」一節。此外README 還提供了可直接嵌入自己專案 README 的「Conventional Commits 1.0.0」徽章 Markdown 片段用於向使用者宣告你的專案遵循此規範。結語把規範變成團隊的默認習慣從本篇文章的完整內容可以看出慣例式提交 1.0.0 的設計哲學是「少量強制 大量彈性」強制只有類型、冒號與描述這三個要素規範第 1、5 條而作用範圍、正文、頁腳、自訂類型、!前綴全部是可選項。正因如此它既能被 commitlint 等 linter 嚴格校驗也能被 standard-version、semantic-release 等工具自動推斷版本號同時又不會束縛團隊自訂類型與工作流程。落地建議很簡單先在提交模板中固定type(scope): description格式再逐步引入「!或BREAKING CHANGE:必須標記重大變更」的審查規則最後接入自動化工具生成 changelog——這份規範會很快成為團隊協作的默認語言。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐如何用 res-downloader 免费下载视频号、抖音与 m3u8 资源如何用 res downloader 免费下载视频号、抖音与 m3u8 资源 一条只在视频号上架了几天的教程视频右键播放器只有转发找不到保存入口。这类资源不桌面应用网络音视频OpenDesign 設計系統包實戰以 Uber 風格為藍本的黑白膠囊化設計規範與 Token 實現解析OpenDesign 設計系統包實戰以 Uber 風格為藍本的黑白膠囊化設計規範與 Token 實現解析 本篇指南以 design systems/uber/AI 应用人工智能AI 技能设计系统媒体生成Thorium浏览器让老 CPU 也能快速跑满的 Chromium 增强方案Thorium浏览器让老 CPU 也能快速跑满的 Chromium 增强方案 标签页开到十几个风扇狂转、内存告急普通浏览器开始转圈。换一份按 CPU 指令桌面应用跨平台上一篇从0开始使用tiny11builder小白友好的图文实操手册下一篇迁移学习实战使用maxvit_rmlp_tiny_rw_256.sw_in1k进行自定义数据集训练创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考