Conventional Commits 1.0.0 规范全解读：从提交信息格式到自动化语义化版本

文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载本文基于本仓库中 约定式提交规范 v1.0.0 的乌克兰语版本content/v1.0.0/index.uk.md对应英文原版 content/v1.0.0/index.md展开系统讲解 Conventional Commits约定式提交规范的完整内容消息结构、类型定义、规范条款、示例与 FAQ。读者学完后将掌握编写符合规范的提交信息、理解其与语义化版本SemVer的映射关系以及为何它能驱动 CHANGELOG 自动生成、版本自动 bump 与构建发布流水线。概述一种轻量级的提交信息约定约定式提交Conventional Commits规范是建立在标准提交信息之上的一种轻量级约定。它提供了一套简单的规则用于创建明确explicit的提交历史从而使在此基础上编写自动化工具变得更加容易。这套约定与语义化版本SemVer自然衔接通过在提交信息中描述新增功能features、缺陷修复fixes与破坏性变更breaking changes工具可以据此推断版本号的变化方向。规范文档使用 RFC 2119 风格的关键词MUST/SHOULD/MAY 等来界定强制性与可选性具体见下文完整规范一节。提交信息的标准结构规范要求提交信息按如下结构组织类型[可选 范围]: 描述 [可选 正文] [可选 页脚一个或多个]其中各部分的含义与书写规则如下fixfix类型的提交用于修补代码库中的缺陷在语义化版本中对应PATCH补丁版本。featfeat类型的提交为代码库引入新功能在语义化版本中对应MINOR次版本。BREAKING CHANGE带有BREAKING CHANGE:页脚、或在类型/范围后追加!的提交引入了破坏性 API 变更对应语义化版本中的MAJOR主版本。BREAKING CHANGE 可以出现在任何类型的提交中。其他类型除fix:与feat:之外的类型同样被允许。例如 commitlint/config-conventional基于 Angular 约定推荐的build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等类型。页脚footers除BREAKING CHANGE: 描述之外还可以提供其他页脚其格式遵循类似于 git trailer format 的约定。需要特别强调的是规范并不强制要求使用额外类型其他类型在语义化版本中也没有隐含的版本影响——除非它们包含 BREAKING CHANGE。此外类型可以附带范围scope范围放在类型后面的括号内用于提供额外的上下文信息例如feat(parser): add ability to parse arrays向解析器新增解析数组的能力。提交信息示例规范文档给出了 7 组可直接照抄的示例覆盖了最常见的组合场景。带描述与 BREAKING CHANGE 页脚的提交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!: send an email to the customer when a product is shipped带范围与!强调破坏性变更的提交feat(api)!: send an email to the customer when a product is shipped同时使用!与 BREAKING CHANGE 页脚的提交feat!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.无正文的提交docs: correct spelling of CHANGELOG带范围的提交feat(lang): add polish language带多段落正文与多个页脚的提交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注意最后一个示例展示了页脚的典型用法Reviewed-by: Z与Refs: #123分别使用:与space#作为分隔符遵循 git trailer 惯例。完整规范本节为规范的正式条款。文档中的关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 与 “OPTIONAL” 均按 RFC 2119 的含义解释MUST必须、MAY可以、SHOULD应当、MUST NOT禁止等。原文条款编号从 12 直接跳到 14本文按内容顺序重新编排为连续编号条款内容一字未删提交信息必须MUST以类型前缀开头类型由名词构成feat、fix等后跟可选的OPTIONAL范围、可选的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 约定。页脚令牌必须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: update ref docs。构成约定式提交的信息单元在实现时不得MUST NOT被视为大小写敏感唯一例外是BREAKING CHANGE它必须MUST全部大写。当BREAKING-CHANGE作为页脚令牌使用时必须MUST与BREAKING CHANGE视为同义词。为什么要使用约定式提交规范文档总结了 5 项核心收益自动生成 CHANGELOG变更日志依据提交信息即可程序化产出发布说明。自动确定语义化版本号 bump基于落地landed的提交类型推断下一个版本是 PATCH、MINOR 还是 MAJOR。向团队成员、公众与其他利益相关方传达变更的性质提交历史本身就是一种可读的沟通载体。触发构建与发布流程工具可根据类型/破坏性变更标记决定是否进入 CI/CD 环节。让更多人更容易为你的项目做贡献结构化、明确的提交历史降低了新贡献者的理解成本。这也正是本仓库 README 所强调的定位本仓库是 约定式提交规范 的官方主页仓库所有版本的规范文本按目录存放于 content 下每个版本对应一个子目录如v1.0.0每个语言一个index.[lang].md文件——例如本文所依据的乌克兰语版本就是 content/v1.0.0/index.uk.md其与英文版 content/v1.0.0/index.md 结构完全一一对应。多语言站点配置则集中在 config.yaml其中uk语言块定义于languages.uk语言名 Ukrainian - Українська。FAQ规范实践中的常见问题规范文档以 FAQ 形式回应了实际落地时的典型疑问以下是全部条目初始开发阶段该如何处理提交信息建议按照产品已经发布的方式来对待提交。通常已经有人在使用你的软件——哪怕只是你的开发同事他们需要知道什么被修复、什么被破坏等。提交标题中的类型用大写还是小写任意大小写均可使用但最好保持一致。如果一次提交同时符合多种类型怎么办尽可能拆分成多个提交。约定式提交的收益之一正是它推动我们做出更有组织的提交和 PR合并请求。这是否会阻碍快速开发与快速迭代它抑制的是无组织的快速推进。它帮助你在长期内、在多个项目、多样化的贡献者之间保持高速迭代。约定式提交会不会让开发者因为只想着预置类型而限制提交类型约定式提交鼓励我们多提交某些类型的提交如 fix。除此之外其灵活性允许团队自定义自己的类型并随时间演进这些类型。这与语义化版本SemVer是什么关系fix类型的提交应对应PATCH发布feat类型的提交应对应MINOR发布任何包含BREAKING CHANGE的提交无论类型都应进入MAJOR发布。使用了规范内的类型但用错了例如用fix代替feat怎么办在合并或发布之前建议使用git rebase -i编辑提交历史来纠正。发布之后的清理方式则取决于你使用的工具与流程。使用了规范之外的类型例如把feat拼成feet怎么办最坏情况下也无碍大局该提交只是不会被基于该规范的工具识别而已。是否所有贡献者都必须按规范写提交不必须如果你采用基于 squash 的合并工作流主维护者在合并时可以清理提交信息——对普通贡献者零额外负担。常见做法是让 Git 平台在合并 PR 时自动 squash 提交并向主维护者提供一个表单由其填写规范的合并提交信息。约定式提交如何处理 revert回滚提交回滚代码可能很复杂你在回滚多个提交吗如果你回滚了一个功能下一个发布应该是补丁吗规范不显式定义 revert 行为而是把逻辑留给了工具作者让他们利用类型types与页脚footers的灵活性来设计回滚处理策略。文档给出的推荐做法是使用revert类型并用页脚引用被回滚提交的 SHArevert: let us never again speak of the noodle incident Refs: 676104e, a215868如何在本地查看这份规范本仓库使用 Hugo 静态站点生成器发布该规范见 README.md。若想在本地查看渲染效果仓库提供了 docker-compose.yml映射端口 1313使用 Dockerfile.dev直接执行docker-compose up后访问http://localhost:1313即可。也可以参考 Makefile 中的make all-dev编译主题资产并hugo serve --bind0.0.0.0来启动开发环境。规范正文经 Hugo 的 single.html 模板渲染为 markdown 文档正文首页的站点介绍、行动按钮则由 welcome.html 渲染。此外仓库的 CONTRIBUTING.md 明确要求所有 Pull Request 都应遵循本规范可见该规范同时也在自我约束着仓库本身的协作流程。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐nixpkgs 中的 haredo 构建钩子为 Hare 项目接管 build / check / install 三个阶段nixpkgs 中的 haredo 构建钩子为 Hare 项目接管 build / check / install 三个阶段 本文围绕 nixpkgs 的 h文档Flipper Zero JS SDK 文件选择器详解pickFile() 从调用到源码实现Flipper Zero JS SDK 文件选择器详解pickFile 从调用到源码实现 在 Flipper Zero 的 JS 应用开发中让用户在设备存储文档Conventional Commits 1.0.0-beta.4 规范详解结构化提交信息与语义化版本发布实践Conventional Commits 1.0.0 beta.4 规范详解结构化提交信息与语义化版本发布实践 Conventional Commits约定文档上一篇依赖注入Dependency Injection实战解析以 Modular Monolith with DDD 的 CancelMeeting 命令为例下一篇如何在Gmail中快速管理GitHub通知GitHub-Gmail扩展完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考