文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载本文以 conventionalcommits.org 仓库中 巴西葡萄牙语版规范 为主体结合仓库内英文权威版本、站点配置与主题源码系统讲解 Conventional Commits 1.0.0 规范的完整语法结构、全部规范条款、典型示例与常见工程问题。读完本文你将能够编写符合规范的提交消息、理解fix/feat/BREAKING CHANGE与语义化版本SemVer的映射关系并知道如何借助该规范驱动 CHANGELOG 自动生成、版本自动提升与构建发布流程。规范概述给提交消息加上人机可读的含义Conventional Commits约定式提交是一种建立在提交消息commit message之上的轻量级约定。它定义了一套简单规则用于创建明确、可解释的提交历史从而让基于该规范编写的自动化工具更容易解析提交、生成文档与版本。该规范与 SemVer语义化版本控制天然契合——通过在提交消息中描述新功能features、缺陷修复fixes和破坏性变更breaking changes自动化的版本号推断成为可能。当前仓库正是这份规范本身的家园根据 README.md仓库使用 Hugo 静态站点生成器组织内容content/v1.0.0/ 目录存放了规范 v1.0.0 的全部语言版本其中 index.md 为英文权威版本index.pt-br.md等文件则是各语言翻译所有新改动应提交到 content/next/即 next 草案版本该文件当前标记为draft: true与正式发布的 1.0.0 相区分。提交消息的标准结构规范要求提交消息按下述模板组织tipo[escopo opcional]: descrição [corpo opcional] [rodapé(s) opcional(is)]即中文对应的通用形式类型[可选范围]: 描述 [可选正文] [可选脚注]一个符合规范的提交由以下部分构成类型type紧跟冒号的动词性名词如fix、feat可选范围scope放在类型后的圆括号中用于补充上下文信息例如feat(parser): adiciona capacidade de interpretar arraysfeat(parser): 增加解析数组的能力描述description冒号与空格之后对代码变更的简短总结可选正文body空行后提供的更详细上下文可选脚注footer正文之后空一行以类似 git trailer 的格式提供元信息。站点 config.yaml 中为各语言配置了页内锚点导航如葡萄牙语的 Resumo 与 Especificação Completathemes/conventional-commits/layouts/_default/single.html 将规范正文渲染为markdown-body文章区配合 welcome.html 展示站点标题与描述说明该规范站点本身也是按内容分层、多语言维护的。三类核心结构化元素规范通过以下元素向库的最终使用者传达意图元素含义与 SemVer 的映射fix:修复代码库中的缺陷对应PATCH补丁版本feat:为代码库引入新功能对应MINOR次版本BREAKING CHANGE在脚注中包含BREAKING CHANGE:文本或在类型/范围后追加!表示引入破坏性 API 变更对应MAJOR主版本其中BREAKING CHANGE 可以出现在任何类型的提交中不限于fix或feat。此外规范允许在fix:与feat:之外使用其他类型例如 commitlint/config-conventional基于 Angular 提交约定推荐的类型包括build:构建系统或外部依赖变更chore:杂务不修改 src 或测试ci:CI 配置与脚本变更docs:仅文档变更style:不影响代码含义的格式变更refactor:既不修 bug 也不加功能的代码重构perf:性能优化test:测试相关变更需要强调的是这些附加类型并非 Conventional Commits 规范强制要求的除非其中包含BREAKING CHANGE否则它们对语义化版本推断没有隐含影响。除BREAKING CHANGE: 描述外还可以提供其他脚注它们遵循与 git trailer 格式 相似的约定例如Reviewed-by:、Refs:等。完整示例集以下示例完整继承自规范文档覆盖了从最简到最复杂的提交形态。示例一带描述与破坏性变更脚注的提交feat: permitir que o objeto de configuração fornecido estenda outras configurações BREAKING CHANGE: a chave extends, no arquivo de configuração, agora é utilizada para estender outro arquivo de configuração示例二用!引起对破坏性变更的注意feat!: envia email para o cliente quando o produto é enviado示例三带范围与!的破坏性变更feat(api)!: envia email para o cliente quando o produto é enviado示例四同时使用!与 BREAKING CHANGE 脚注葡萄牙语版文档给出的示例如下feat:! remove suporte para Node 6 BREAKING CHANGE: refatorar para usar recursos do JavaScript não disponíveis no Node 6.需要说明根据规范条款!必须紧跟冒号之前标准写法为feat!: remove suporte para Node 6英文权威版 index.md 中的对应示例正是feat!:形式葡萄牙语版此处为翻译/排版差异读者按规范条款书写即可。示例五无正文的提交docs: ortografia correta de CHANGELOG示例六带范围的提交feat(lang): adiciona tradução para português brasileiro示例七引用工单号可选的修复提交fix: corrige pequenos erros de digitação no código veja o ticket para detalhes sobre os erros de digitação corrigidos Revisado por: Daniel Nass Refs #133注意此例展示了脚注的两种分隔符用法Revisado por: ...空格分隔与Refs #133空格#分隔正是规范中脚注分隔符条款的实践体现。规范条款逐条精读RFC 2119 语义规范全文使用 RFC 2119 定义的关键词——必须MUST禁止MUST NOT要求REQUIRED应当SHALL不应当SHALL NOT应该SHOULD不应该SHOULD NOT建议RECOMMENDED可以MAY可选OPTIONAL——来精确表达要求的强度。全部 15 条规则整理如下提交消息必须以类型为前缀类型由名词构成feat、fix等后跟可选的scope、可选的!并且必须以冒号和空格结尾强制。feat类型必须用于为应用或库添加新功能的提交。fix类型必须用于修复应用或库缺陷的提交。范围可以MAY在类型之后提供范围必须是描述代码库某一部分的名词且放在圆括号中如fix(parser):。描述必须在类型/范围前缀的冒号与空格之后立即存在是对代码变更的简短总结例如fix: problema na interpretação do array quando uma string tem vários espaços。更长的正文可以MAY在简短描述之后提供用于补充变更上下文正文必须在描述之后空一行开始。正文是自由格式的可以MAY由任意数量的、以换行分隔的段落组成。可以在正文之后空一行提供一条或多条脚注每条脚注必须由一个词 token、一个分隔符:空格或空格#以及一个字符串值组成受 git trailer 约定 启发。脚注 token 中必须用-代替空白字符例如Acked-by这有助于将脚注区与多段落的正文区分开例外BREAKING CHANGE也可以MAY直接作为 token 使用。脚注的值可以MAY包含空格和换行解析parsing必须在观察到下一个合法的脚注 token/分隔符组合时终止。破坏性变更必须MUST通过以下两种方式之一声明在提交的类型/范围前缀中标注或作为脚注条目提供。若以脚注形式声明破坏性变更必须由大写文本BREAKING CHANGE、冒号、空格和描述组成例如BREAKING CHANGE: as variáveis de ambiente agora têm precedência sobre os arquivos de configuração。若在前缀中声明破坏性变更必须通过在:前紧跟!表示使用!后脚注中的BREAKING CHANGE:可以省略此时应SHALL用提交描述来阐述该破坏性变更。feat与fix之外的类型可以使用MAY例如docs: documentos de referência atualizados。构成 Conventional Commits 的信息单元不得被实现者区分大小写唯一例外是BREAKING CHANGE必须大写且BREAKING-CHANGE作为脚注 token 时必须与BREAKING CHANGE视为同义词。从实现角度看这些条款为解析器工具规定了明确的边界条件例如第 910 条决定了脚注解析器如何区分多段正文与脚注区第 13 条允许!与BREAKING CHANGE:二选一从而简化了提交书写。规范的演进草案 content/next/index.md 在此基础上还在探索!!与INITIAL STABLE RELEASE等新机制当前仅存在于 draft 中不属于 1.0.0 正式范围。为什么使用 Conventional Commits规范文档明确列举了五大收益自动生成 CHANGELOG基于结构化的提交历史工具可自动汇总每次发布的功能、修复与破坏性变更。自动确定语义化版本提升根据落地的提交类型fix→ PATCH、feat→ MINOR、BREAKING CHANGE → MAJOR自动推算下一个版本号。向团队成员、公众与其他利益相关者传达变更性质提交消息本身就是面向人类的变更说明。触发构建与部署流程CI 可根据提交类型决定是否发布、如何发布。降低他人参与贡献的门槛结构化的提交历史让新贡献者更容易理解项目演变。这些收益正是当前仓库作为规范官方驻地被各语言持续翻译维护的原因仓库 config.yaml 中配置了 20 余种语言的站点信息含每种语言当前指向的版本号与版本列表保证全球开发者都能以母语阅读同一份规范而_redirects文件将根路径重定向到/en/v1.0.0/确保英文权威版作为默认入口。常见问题FAQ与最佳实践开发初期如何处理提交消息建议把产品当作已经发布来写提交。通常某个人——哪怕只是你身边的同事——正在使用你的软件他们会想知道什么被修复、新增了什么功能、有哪些破坏性变更。提交标题中的类型应该大写还是小写两种都可以但最好保持一致。如果一个提交同时符合多种类型怎么办尽可能拆分并创建多个提交。Conventional Commits 的收益之一正是促使我们提交更有序、PR 更清晰。这是否会阻碍快速开发与快速迭代它阻止的是杂乱无章的快速帮助你在多个项目、多样贡献者的长期协作中持续保持高速。是否会让开发者因想类型而限制提交恰恰相反Conventional Commits鼓励你更多地提交特定类型如修复。同时它的灵活性允许团队自定义自己的类型并随时间演进这些类型。与 SemVer 的具体关系是什么fix类型提交 → 对应PATCH发布feat类型提交 → 对应MINOR发布含BREAKING CHANGE的提交无论类型→ 对应MAJOR发布。如何为规范自身的扩展如jameswomack/conventional-commit-spec版本化建议使用 SemVer 来发布你对本规范的扩展官方也鼓励大家创建这类扩展。不小心用错了提交类型怎么办用了规范内但错误的类型如把feat写成了fix在合并或发布之前建议使用git rebase -i编辑提交历史发布之后的清理方式则取决于你所用的工具与流程。用了规范外的类型如把feat拼成feet最坏情况下也不是世界末日——该提交只是会被基于本规范的工具忽略而已。所有贡献者都必须遵守本规范吗不必如果团队采用基于 squash 的 Git 工作流主维护者可以在合并时清理提交消息不会给普通提交者增加负担。常见做法是让 Git 系统在合并 pull request 时自动 squash 提交并向主维护者呈现一个表单由其在合并时填写规范的提交消息。如何处理 revert回滚提交回滚代码可能很复杂你回滚了多个提交吗回滚一个功能时下一版本应该是一个 patch 吗规范不强制定义回滚行为而是留给工具作者利用类型与脚注的灵活性自行设计逻辑。文档给出的一条推荐做法是使用revert类型 引用被回滚提交 SHA 的脚注revert: nunca mais falaremos do incidente do miojo Refs: 676104e, a215868在仓库中进一步探索如果你希望对照原文或参与贡献可以在当前仓库中阅读英文权威版本 content/v1.0.0/index.md以及各语言翻译如index.pt-br.md、index.zh-hans.md等查看仍在草案阶段的未来版本 content/next/index.md注意其 front matter 为draft: true不属于 1.0.0 发布内容了解站点结构README.md 说明了 content 目录约定与本地运行方式仓库提供了 docker-compose.yml可执行docker-compose up后在http://localhost:1313预览站点查看站点主题实现themes/conventional-commits/layouts/_default/single.html 渲染规范正文themes/conventional-commits/layouts/partials/header.html 提供版本与语言下拉切换版本列表来自 config.yaml。小结Conventional Commits 1.0.0 用一组极简的语法规则类型 可选范围 描述 可选正文 可选脚注为提交历史赋予了结构化语义并通过对fix、feat与BREAKING CHANGE的精确定义与 SemVer 形成稳定的映射。对于团队而言落地这套规范意味着CHANGELOG 可以自动生成、版本号可以自动推断、构建发布可以被自动触发、贡献门槛随之降低对于工具开发者而言规范中 15 条带 RFC 2119 语义的条款则为解析、校验与版本推断工具提供了精确的实现边界。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐Conventional Commits 1.0.0 规范全解析commit 消息结构、SemVer 映射与落地实践Conventional Commits 1.0.0 规范全解析commit 消息结构、SemVer 映射与落地实践 导读 本文以 conventionalc文档Conventional Commits 1.0.0 规范详解结构化提交信息与语义化版本自动化实践Conventional Commits 1.0.0 规范详解结构化提交信息与语义化版本自动化实践 本文以本仓库 content/v1.0.0/index.m文档Conventional Commits 1.0.0-beta.2 规范深度解读结构化提交信息与语义化版本自动化实践Conventional Commits 1.0.0 beta.2 规范深度解读结构化提交信息与语义化版本自动化实践 本指南以 conventionalcom文档上一篇MiUnlockTool完全解析小米设备Bootloader解锁终极指南下一篇OpenWorkflow与Temporal/BullMQ对比为什么它是更优选择创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考