文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载导读本文以 content/v1.0.0/index.uz.mdConventional Commits 1.0.0 规范的乌兹别克语官方翻译为核心骨架系统讲解 commit 消息的标准化结构、16 条规范细则、7 类实战示例以及与 SemVer 的对应关系并结合本仓库的 Hugo 站点配置与源码说明该规范在 conventionalcommits.org 项目中如何组织与发布。读完本文你将掌握一套既能让人类读懂的、又能被自动化工具CHANGELOG 生成、语义化版本推算、CI 发布触发解析的统一 commit 写法。概述什么是 Conventional CommitsConventional Commits 规范是一套建立在 commit 消息之上的轻量级约定lightweight convention。它提供了一组简单规则用于创建结构清晰、意图明确的 commit 历史从而让基于 commit 历史编写自动化工具变得更加容易。该规范与 SemVer语义化版本紧密相关——commit 消息中描述的新特性features、缺陷修复fixes和破坏性变更breaking changes会直接映射到版本号的 MINOR、PATCH 与 MAJOR 递增上。从本仓库的站点结构可以看出该规范以多语言方式发布content/v1.0.0/目录下同时维护了英文原版 index.md 与乌兹别克语翻译版 index.uz.md 等数十种语言版本config.yaml 中为每种语言都配置了独立站点参数其中乌兹别克语uz语言块的aliases: [/uz/]声明于文档 front matter 中defaultContentLanguageInSubdir: true保证每种语言版本都能以独立子路径访问。commit 消息的标准结构按照规范一条 commit 消息必须按下述形式组织类型[可选 作用域]: 描述 [可选 正文] [可选 页脚]该结构包含以下核心结构元素用于向你的库的消费者传达变更意图fix:类型为fix的 commit 修复代码库中的缺陷对应语义化版本中的PATCH。feat:类型为feat的 commit 为代码库引入新特性对应语义化版本中的MINOR。BREAKING CHANGE:带有BREAKING CHANGE:页脚、或在类型/作用域之后追加!的 commit代表对现有 API 的破坏性变更对应语义化版本中的MAJOR。BREAKING CHANGE 可以出现在任何类型的 commit 中。除fix:与feat:之外的其他类型同样被允许例如 commitlint/config-conventional基于 Angular 约定推荐的build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等。除BREAKING CHANGE: 描述之外还可以提供其他页脚并遵循与 git trailer 格式相似的约定。规范不强制要求额外类型且除非包含 BREAKING CHANGE额外类型对语义化版本没有隐式影响。可以为 commit 类型附加作用域scope用圆括号包裹以提供更多上下文信息例如feat(parser): add ability to parse arrays。实战示例七类典型 commit 消息规范文档给出了 7 个可直接套用的示例覆盖了破坏性变更、作用域、正文与页脚的各种组合示例 1带描述与 BREAKING CHANGE 页脚的 commitfeat: allow provided config object to extend other configs BREAKING CHANGE: extends key in config file is now used for extending other config files示例 2用!引起注意的破坏性变更feat!: send an email to the customer when a product is shipped示例 3同时使用作用域与!的破坏性变更feat(api)!: send an email to the customer when a product is shipped示例 4同时使用!与 BREAKING CHANGE 页脚的 commitfeat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.示例 5无正文的 commitdocs: correct spelling of CHANGELOG示例 6带作用域的 commitfeat(lang): add Polish language示例 7多段落正文与多个页脚的 commitfix: 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最后一个示例展示了正文与页脚的完整形态正文可以包含多个由空行分隔的段落页脚区域使用Reviewed-by: Z、Refs: #123这类 词令牌 分隔符 值 的形式与 git trailer 约定一致。规范正文16 条 MUST / MAY 细则本规范中的关键词 MUST必须、MUST NOT禁止、REQUIRED要求、SHALL应当、SHALL NOT不应当、SHOULD建议、SHOULD NOT不建议、RECOMMENDED推荐、MAY可以与 OPTIONAL可选均按 RFC 2119 的定义解释。完整细则如下类型前缀MUSTcommit 必须以一个名词性类型feat、fix等开头随后是可选的OPTIONAL作用域、可选的OPTIONAL!以及必需的REQUIRED终结冒号与空格。feat 的使用MUST当 commit 为你的应用或库添加新特性时必须使用feat:类型。fix 的使用MUST当 commit 修复应用中的缺陷时必须使用fix:类型。作用域MAY类型之后可以MAY提供作用域。作用域必须MUST由描述代码库某一区域的、用圆括号包裹的名词构成例如fix(parser):。描述MUST描述必须MUST紧跟类型/作用域前缀后的冒号与空格。描述是对代码变更的简短总结例如fix: array parsing issue when multiple spaces were contained in string。正文MAY短描述之后可以MAY提供更长的 commit 正文为代码变更提供额外上下文信息。正文必须MUST在描述之后隔一个空行开始。正文的自由格式MAY正文是自由格式的可以MAY由任意数量的、以换行分隔的段落组成。页脚MAY正文之后空一行可以MAY提供一个或多个页脚。每个页脚必须MUST由词令牌开始后跟:空格或空格#分隔符再跟一个字符串值受 git trailer 约定启发。页脚令牌的连字符规则MUST页脚令牌中必须MUST使用-代替空白字符例如Acked-by这有助于将页脚区域与多段落正文区分开。唯一例外是BREAKING CHANGE它也可以MAY直接用作令牌。页脚值MAY页脚值可以MAY包含空格和换行解析必须在观察到下一个有效页脚令牌/分隔符对时终止MUST。破坏性变更的标示位置MUST破坏性变更必须MUST在 commit 的类型/作用域前缀中或以页脚条目的形式标示。作为页脚的 BREAKING CHANGEMUST若以页脚形式出现破坏性变更必须MUST由大写文本BREAKING CHANGE组成后跟冒号、空格和描述例如BREAKING CHANGE: environment variables now take precedence over config files.。前缀中的!MUST若在类型/作用域前缀中标示破坏性变更必须MUST在:之前立即使用!。若使用了!可以MAY省略页脚中的BREAKING CHANGE:此时应当SHALL用 commit 描述来说明破坏性变更。其他类型MAYcommit 消息中可以使用MAY除feat与fix之外的类型例如docs: update ref docs.。大小写敏感性MUST NOT构成 Conventional Commits 的信息单元不得MUST NOT被实现者视为大小写敏感唯一的例外是BREAKING CHANGE它必须MUST大写。BREAKING-CHANGE 同义词MUST当BREAKING-CHANGE作为页脚令牌使用时必须MUST与BREAKING CHANGE同义。从实现角度看这 16 条细则共同定义了自动化工具所需的全部解析规则。仓库 content/about/index.md 收录了完整的工具生态清单例如 conventional-changelog从 git 历史解析 Conventional Commits 消息的工具集、commitlint校验 commit 消息是否符合格式的 linter、semantic-release自动确定下一个版本号并生成 release notes等它们正是这些 MUST/MAY 规则的落地实现者。为什么使用 Conventional Commits采用该规范可以带来五个直接的工程收益自动生成 CHANGELOG基于类型化 commit 历史工具可以自动整理变更清单。自动确定语义化版本递增根据已合入 commit 的类型feat/fix/BREAKING CHANGE自动判断版本号应如何 bump。向团队、公众和其他利益相关者传达变更性质commit 消息本身成为可读的变更说明。触发构建与发布流程CI/CD 可以根据 commit 类型或破坏性变更标记决定是否触发构建、发布。降低贡献门槛结构化的 commit 历史让新人更容易浏览项目从而更方便地为你的项目做贡献。对应到本仓库README.md 中给出了可以直接嵌入项目 README 的徽章badge代码向用户声明本项目遵循 Conventional Commits 1.0.0 规范这也是规范生态机器可读特性的体现。FAQ常见问题与官方解答规范文档在 FAQ 部分集中回答了 12 个高频疑问以下是官方观点1. 初始开发阶段的 commit 消息怎么处理建议将产品视为已经发布来推进。通常总有人哪怕是你的开发同事在使用你的软件他们需要知道什么被修复了、什么被破坏了。2. commit 类型用大写还是小写任何大小写都可以使用但最好保持一致。3. 一个 commit 同时符合多种类型怎么办尽可能拆分回退并创建多个 commit。Conventional Commits 的收益之一正是它能驱动我们做出更有序的 commit 与 PR。4. 这会阻碍快速开发与快速迭代吗它阻止的是无序地快。它能帮助你在长期、跨多个项目、面对多样化贡献者的场景下保持快速推进。5. 规范会不会让开发者只局限于推荐类型Conventional Commits 鼓励更多地进行特定类型如 fix的提交除此之外规范的灵活性允许你的团队自定义类型并随时间演进这些类型。6. 这与 SemVer 是什么关系fix类型 commit 应映射为PATCH发布feat类型 commit 应映射为MINOR发布包含BREAKING CHANGE的 commit无论类型应映射为MAJOR发布。7. 如何给自己的规范扩展如jameswomack/conventional-commit-spec定版本建议使用 SemVer 来发布你对该规范的扩展并鼓励大家创建扩展。8. 误用了类型如应写feat却写了fix怎么办在合并或发布之前建议使用git rebase -i编辑 commit 历史发布之后清理方式将取决于你使用的工具与流程。9. 使用了规范之外的类型如把feat写成feet怎么办最坏情况下如果合入了一个不符合规范的 commit也不是世界末日——它只是意味着基于该规范的自动化工具会跳过这个 commit。10. 所有贡献者都必须遵循规范吗不必如果采用基于 squash 的合并工作流主维护者可以在合并时清理 commit 消息不会给普通贡献者增加负担。常见做法是让 git 系统自动 squash PR 中的 commits并向主维护者呈现一个表单由维护者填写正确的合并 commit 消息。11. 如何处理 revert回滚commit回滚代码可能很复杂你回滚的是多个 commit 吗回滚一个特性时下一个版本应该改为 PATCH 吗规范并不尝试显式定义回滚行为而是把决定权留给工具作者让他们利用类型与页脚的灵活性来设计回滚逻辑。一个推荐做法是使用revert类型并用页脚引用被回滚的 commit SHArevert: let us never again speak of the noodle incident Refs: 676104e, a21586812. 规范如何与自动化工具协同对应如何匹配多个 commit 类型的延伸 规范的价值正在于人机可读——正如 config.yaml 中乌兹别克语语言的描述所写为 commit 消息添加人和机器都能读取的意义。仓库视角规范文档在 conventionalcommits.org 中的组织方式conventionalcommits.org 是一个基于 Hugo 构建的多语言静态站点本仓库即其源码。理解它的组织方式有助于你定位规范文档、查阅翻译、甚至本地预览版本目录content/下按版本号组织如 content/v1.0.0/、v1.0.0-beta.4/等每个目录内的index.md是英文原版index.[语言代码].md是对应翻译如本文依据的 index.uz.md。语言配置config.yaml 中为每种语言配置了weight排序权重、title、description、页面锚点动作和版本列表乌兹别克语uz的current: v1.0.0与本文档版本一致。渲染布局规范正文通过 themes/conventional-commits/layouts/_default/single.html 中的article classmarkdown-body渲染页首的欢迎区由 themes/conventional-commits/layouts/partials/welcome.html 输出站点标题、描述与操作按钮。本地预览仓库提供 docker-compose.yml 与 Makefile安装 docker-compose 后执行docker-compose up即可在http://localhost:1313本地查看站点效果参见 README.md。规范演进content/next/index.md 用于承载仍在修订中的下一版本草案正式版本则固化在各版本目录中。总结Conventional Commits 1.0.0 以类型 可选作用域 描述 可选正文 可选页脚的固定结构为 commit 消息赋予了同时面向人类与机器的意义。其 16 条规范细则精确界定了 MUST必须与 MAY可以的边界7 个示例覆盖了破坏性变更、作用域、正文与页脚的全部组合12 个 FAQ 解决了团队落地时最常遇到的疑问。无论你是想接入 commitlint 做提交校验、用 semantic-release 实现自动发布还是只想让团队的 git 历史变得更可读都可以从本文继承的这套规范原文直接开始实践。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐Conventional Commits 1.0.0-beta.4 规范详解从结构化 Commit 消息到语义化版本自动化Conventional Commits 1.0.0 beta.4 规范详解从结构化 Commit 消息到语义化版本自动化 Conventional Comm文档Sa-Token OAuth2 注解鉴权实战SaCheckAccessToken、SaCheckClientToken、SaCheckClientIdSecret 使用与原理Sa Token OAuth2 注解鉴权实战SaCheckAccessToken、SaCheckClientToken、SaCheckClientIdS文档Haystack 集成 Llama StackLlamaStackChatGenerator 使用与参数全解Haystack 集成 Llama StackLlamaStackChatGenerator 使用与参数全解 导读 本文围绕 Haystack 对 Llama文档上一篇如何快速掌握Spark机器学习算法10个核心算法原理详解下一篇WebdriverIO 网络 Mock 对象Mock Object完全指南拦截、伪造与断言浏览器网络请求创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考