文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载本篇文章以仓库中 content/v1.0.0-beta.1/index.zh-hans.md 为规范原文主体并结合本仓库conventionalcommits.org即 Conventional Commits 规范官方站点源码中的多语言版本、站点配置与主题实现进行佐证和扩充帮助你在自己的项目里落地这一套轻量、人机可读的提交信息约定。导读约定式提交Conventional Commits是一套建立在提交说明commit message之上的轻量级约定它要求开发者在每一次提交中用类型[可选作用域]: 描述的结构声明本次变更的性质——是修复、是新功能、还是破坏性变更从而与语义化版本SemVer一一对应。读完本文你将掌握 1.0.0-beta.1 规范的全部条文与每个字段的写作要求能够据此编写可被 commitlint、semantic-release 等自动化工具解析的提交信息并理解本仓库如何以多语言文档站的形式发布这份规范、如何在自己的仓库中引用与校验它。一、规范概述提交说明的标准结构规范原文开篇即点明其适用场景作为开源维护者在将特性分支合并squash入master时可以编写标准化的提交说明。提交说明的整体结构为类型[可选的作用域]: 描述 [可选的正文] [可选的页脚]这一结构在英文原文content/v1.0.0-beta.1/index.md与中文译文content/v1.0.0-beta.1/index.zh-hans.md中完全一致。提交说明由此包含下述结构化元素向类库使用者表明其意图fix类型为fix的提交表示在代码库中修复了一个 bug这与语义化版本中的PATCH相对应。feat类型为feat的提交表示在代码库中新增了一个功能这与语义化版本中的MINOR相对应。BREAKING CHANGE在可选的正文或页脚的起始位置带有BREAKING CHANGE:的提交表示引入了破坏性变更这与语义化版本中的MAJOR相对应。破坏性变更可以是任意类型提交的一部分对于fix:、feat:和chore:乃至更多其它的类型而言它都是有效的。除此之外fix:和feat:之外的其它提交类型也都是支持的例如 Angular 约定中推荐使用的docs:、style:、refactor:、perf:、test:、chore:但这些标签在约定式提交规范中并不是强制性的。作用域scope为类型补充上下文可以为提交类型添加一个围在圆括号内的作用域以提供额外的上下文信息。例如feat(parser): add ability to parse arrays.作用域描述的通常是代码库中的某个部分模块、组件、子系统它让读者在扫过提交历史时能立即定位变更影响面。二、为什么需要约定式提交动机与背景规范正文的“介绍”章节解释了这一约定的由来。在软件开发中经验表明 bug 最常由应用间的边界引入单元测试在所测试的交互处于开源维护者知识范围内时工作得很好但在刻画社区里各种有趣而常在预料之外的使用场景时就显得比较糟糕了。任何在升级新依赖 patch 版本后发现应用开始抛出稳定 500 错误流的人都知道可读的提交历史以及理想条件下高质量维护的 CHANGELOG对后续排障有多重要。约定式提交规范提议在提交说明的基础上引入标准化的轻量约定。这个约定与 SemVer 相吻合要求开发者在提交信息中描述新特性、bug 修复和破坏性更新。引入这一约定后我们可以创建一种通用的语言简化在项目边界之间调试的问题——提交信息不再只是写给 git 的注释而是团队成员、下游消费者乃至机器工具都能读懂的结构化数据。三、约定式提交规范完整条文逐条解读规范正文指出文档中的关键词“必须MUST”、“禁止MUST NOT”、“需要REQUIRED”、“应当SHALL”、“不应当SHALL NOT”、“应该SHOULD”、“不应该SHOULD NOT”、“推荐RECOMMENDED”、“可以MAY”和“可选OPTIONAL”应按照 RFC 2119 的描述解释。理解这套强度分级是正确落地规范的前提——必须意味着无条件的强制要求应当/应该意味着正常情况下应遵循、存在合理例外而可以/可选则表示完全自由裁量。规范共十条逐条解读如下每个提交都必须使用类型字段前缀这由一个形如feat或fix的名词组成其后接冒号和空格。注意英文半角冒号与空格是语法的一部分机器解析依赖这一精确格式。当一个提交为应用或类库实现了新特性时必须使用feat类型。这是类型与语义化版本MINOR挂钩的基础。当一个提交为应用修复了 bug 时必须使用fix类型。这是类型与语义化版本PATCH挂钩的基础。可选的作用域字段可以在类型后提供。作用域是描述代码库中某个部分的词组封装在圆括号中形如fix(parser):。描述字段必须紧接在类型或作用域前缀之后。描述是对 pull request 的简短描述例如fix: array parsing issue when multiple spaces were contained in string.。在简短描述之后可以编写更长的提交正文。正文必须起始于描述字段结束的一个空行后空行是分隔描述与正文的语法边界。在正文结束的一个空行后可以编写页脚。页脚应当包含额外的元信息例如它所修复的 issue类似fixes #13, #5。破坏性变更必须在提交的正文或脚注中展示。一个破坏性变更必须包含大写的文本BREAKING CHANGE紧跟冒号和空格。注意此处要求“正文或脚注的起始位置”这一位置约束是 1.0.0-beta.1 阶段与最终版规范差异较大的地方详见下文“规范演进”一节。在BREAKING CHANGE:之后必须提供描述以描述对 API 的变更。例如BREAKING CHANGE: environment variables now take precedence over config files.。在提交说明中可以使用feat和fix之外的类型。这意味着规范鼓励团队扩展自己的类型体系只要保持同样的语法结构即可被工具识别。一份符合规范的完整提交示例将上述条文组合起来一个完整的提交说明长这样feat(parser): add ability to parse arrays Implement recursive descent parsing for nested array literals, handling trailing commas per the project style guide. BREAKING CHANGE: array elements must now be separated by commas fixes #13, #5其中类型为feat、作用域为parser、描述句紧随冒号空格空行后是正文段落再次空行后是页脚——既包含了BREAKING CHANGE:破坏性变更声明也包含了fixes #13, #5的 issue 引用元信息。四、为什么使用约定式提交五大收益规范用五个要点概括了这一约定带来的直接价值自动化生成 CHANGELOG工具可以按类型分组聚合提交信息直接产出可发布的更新日志。基于提交的类型自动决定语义化的版本变更fix升 PATCH、feat升 MINOR、含BREAKING CHANGE升 MAJOR版本号的决策逻辑被完全程序化。向同事、公众与其他利益关系人传达变化的性质任何人在浏览提交历史时都能迅速判断每个提交的意图。触发构建和部署流程CI/CD 系统可以根据提交类型决定是否需要发布、发布何种版本。让人们更容易地探索结构化的提交历史降低贡献项目的难度新贡献者通过类型标签即可快速理解项目演变脉络。五、仓库中的这份规范站点结构、多语言与本地运行本仓库conventionalcommits.org正是用 Hugo 静态站点生成器承载这份规范的官方站点。README.md 说明了仓库布局content目录存放规范的所有版本content/next/存放进行中的草案content/**/index.[lang].md则按语言后缀存放各版本译文——不带语言后缀的是规范原文带后缀的是翻译。本文所依据的 content/v1.0.0-beta.1/index.zh-hans.md 即是 1.0.0-beta.1 版本的中文简体翻译。站点配置见 config.yamltheme: conventional-commits指定了位于 themes/conventional-commits 的主题defaultContentLanguage: en与defaultContentLanguageInSubdir: true决定英文为默认语言且各语言以子目录形式发布。在languages配置块中zh-hans语言条目声明了标题“约定式提交”、描述“一种用于给提交信息增加人机可读含义的规范”并在versions.list中列出了当前展示的版本序列v1.0.0、v1.0.0-beta.4、v1.0.0-beta.3、v1.0.0-beta.2、v1.0.0-beta.1、v1.0.0-beta。站点头部的“Versions / Languages”下拉菜单正是由主题 themes/conventional-commits/layouts/partials/header.html 依据这些配置渲染的页面正文则通过 _default/single.html 将规范内容套入 GitHub 风格 Markdown 样式展示。如果你希望在本机预览这份规范文档仓库提供了 docker-compose.yml安装 docker-compose 后执行docker-compose up站点编译完成后访问http://localhost:1313即可浏览。另外README 还提供了官方徽章badge代码用于在自己的项目 README 中声明“本项目遵循 Conventional Commits 规范”这既是规范在社区中传播的载体也方便贡献者与工具一眼识别项目的提交风格。六、规范演进从 1.0.0-beta.1 到 1.0.0 正式版的关键差异阅读本仓库可以发现1.0.0-beta.1 并非最终形态。对照正式版译文 content/v1.0.0/index.zh-hans.md后续版本主要在以下几处做出了调整理解这些差异有助于你判断项目应采用哪个版本的约定破坏性变更的标记位置beta.1 要求BREAKING CHANGE:位于正文或页脚的起始位置正式版进一步允许在类型(范围)前缀中、冒号之前直接写!如feat!: ...、feat(api)!: ...来标记破坏性变更且!与BREAKING CHANGE:脚注可以二选一。脚注的语法约束正式版将脚注规则细化为 git trailer 惯例——每行脚注须包含一个 token后接:space或space#分隔符再跟值token 中的连字符用-如Acked-by并规定工具实现解析时不得区分大小写、BREAKING-CHANGE是BREAKING CHANGE的同义词。beta.1 阶段对这些细节尚无明确约束。新增“示例”章节与还原revert提交讨论正式版加入了大量可直接复制的示例含!、多行正文与多行脚注的组合并在 FAQ 中补充了还原提交的处理建议推荐revert类型加Refs:脚注。这些差异清楚地表明规范本身也在迭代团队在选型时应以当前目标版本本仓库默认展示 v1.0.0的条文为准。七、FAQ落地过程中的常见问题规范原文以 FAQ 形式回答了实操中几乎必然会遇到的问题全部要点如下。如何处理初始开发阶段的提交说明建议按照已发布的产品那样来处理。一般情况下即便是开发者同事也有人使用你的软件他们会希望知道诸如修复了什么、哪里不兼容等信息。从第一天就遵守规范避免日后重写历史。提交符合一或多种类型时该如何处理回退并尽可能创建多次提交。约定式提交的部分好处是能够促使我们做出更有组织的提交和 PR——一个提交只做一件事类型归属自然清晰。这不会阻碍快速的开发和迭代吗它阻碍的是以杂乱无章的方式快速前进而不是快速本身。它帮助我们在横跨长时间周期、多个项目、多个贡献者时能够保持效率。约定式提交会让开发者受限于提交的类型吗约定式提交鼓励我们更多地使用某些类型的提交比如 fixes。除此之外约定式提交的灵活性也允许你的团队使用自己的类型并随着时间的推移更改这些类型——第 10 条明文允许自定义类型。这和 SemVer 有什么关联呢fix类型提交应当对应到PATCH版本feat类型提交应该对应到MINOR版本带有BREAKING CHANGE的提交不管类型如何都应该对应到MAJOR版本。这一映射是整个自动版本管理工具链如 semantic-release、standard-version 等的运算基础。我对约定式提交做了形如jameswomack/conventional-commit-spec的扩展该如何版本化管理这些扩展呢推荐使用 SemVer 来发布你对于这个规范的扩展规范鼓励创建这些扩展——扩展本身也是软件同样适用规范的分级逻辑。如果我不小心使用了错误的提交类型该怎么办呢分两种情况当你使用了在规范中但错误的类型时如将feat写成了fix在合并或发布这个错误之前建议使用git rebase -i来编辑提交历史而在发布之后根据你使用的工具和流程不同会有不同的清理方案。当使用了不在规范中的类型时如将feat写成了feet在最坏的场景下即便提交没有满足规范也不是世界的终结只是这个提交会被基于规范的工具错过而已——它不会破坏任何东西只是无法被自动分类。所有的贡献者都需要使用约定式提交规范吗并不如果你使用基于 squash 的 Git 工作流主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。一种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交向主管维护者提供表单来在合并时输入合适的 git 提交信息。这意味着规范可以只约束合并入口而不给每一位贡献者增加摩擦。八、在真实项目中落地从规范到工具链本仓库的 content/about/index.md 记载了规范与生态工具的渊源规范受 Angular 提交指南启发首版草案是与 conventional-changelog、parse-commit-message、lerna 等工具的维护者协作完成的并持续列出了一系列基于规范的工具例如commitlint校验提交信息是否符合规范、commitizen/cz-cli交互式生成合规提交信息、semantic-release依据提交类型自动决定版本号并发布、standard-version自动版本管理与 CHANGELOG 生成、git-cliffRust 编写的可定制 CHANGELOG 生成器等。从源码结构看规范本身不绑定任何语言或平台只要工具按类型[作用域]: 描述加 RFC 2119 强度语义解析就能在任意技术栈中复用。落地建议可归纳为三步第一步在团队贡献指南中引用规范原文即本仓库中的对应版本文档第二步在 CI 或 git 钩子中接入 commitlint 等校验工具把“必须”级条文变成可执行的检查第三步用 semantic-release 或 standard-version 将fix/feat/BREAKING CHANGE自动映射为 PATCH/MINOR/MAJOR 版本并生成 CHANGELOG。三件事做完提交信息就从“给人看的文字”升级为“驱动发布流程的数据”。结语约定式提交 1.0.0-beta.1 用十条规则定义了一种极简但机器可解析的提交信息语法类型声明变更性质、作用域定位变更范围、正文与页脚承载细节与元信息、BREAKING CHANGE标记破坏性变更。它不强制团队使用哪些类型却强制提交具备一致的骨架——正是这种“结构上的严格、内容上的自由”让它既能被工具自动处理又能长期适应团队自己的演化。本文以 content/v1.0.0-beta.1/index.zh-hans.md 为骨架对照 config.yaml 与主题布局还原了规范的发布形态并对比 content/v1.0.0/index.zh-hans.md 梳理了规范自身的演进脉络。如果你的项目正准备引入这套约定建议以当前正式版 v1.0.0 为准同时以上述 FAQ 与工具链路径作为落地参考。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐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 规范详解用结构化提交消息驱动版本管理与自动化工具 本篇指南以开源仓库 convention文档Conventional Commits 1.0.0-beta 规范全解结构化提交信息与 SemVer 自动化协作指南Conventional Commits 1.0.0 beta 规范全解结构化提交信息与 SemVer 自动化协作指南 本指南以仓库内 content/v1.文档上一篇ToastFish 桌面弹窗背单词摸鱼间隙30秒记住一个新词下一篇CC Switch 在 Windows 上装完打不开跟着症状一步步定位创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 约定式提交（Conventional Commits）1.0.0-beta.1 规范详解：以结构化提交信息驱动版本管理与 CHANGELOG 自动化
文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载本篇文章以仓库中 content/v1.0.0-beta.1/index.zh-hans.md 为规范原文主体并结合本仓库conventionalcommits.org即 Conventional Commits 规范官方站点源码中的多语言版本、站点配置与主题实现进行佐证和扩充帮助你在自己的项目里落地这一套轻量、人机可读的提交信息约定。导读约定式提交Conventional Commits是一套建立在提交说明commit message之上的轻量级约定它要求开发者在每一次提交中用类型[可选作用域]: 描述的结构声明本次变更的性质——是修复、是新功能、还是破坏性变更从而与语义化版本SemVer一一对应。读完本文你将掌握 1.0.0-beta.1 规范的全部条文与每个字段的写作要求能够据此编写可被 commitlint、semantic-release 等自动化工具解析的提交信息并理解本仓库如何以多语言文档站的形式发布这份规范、如何在自己的仓库中引用与校验它。一、规范概述提交说明的标准结构规范原文开篇即点明其适用场景作为开源维护者在将特性分支合并squash入master时可以编写标准化的提交说明。提交说明的整体结构为类型[可选的作用域]: 描述 [可选的正文] [可选的页脚]这一结构在英文原文content/v1.0.0-beta.1/index.md与中文译文content/v1.0.0-beta.1/index.zh-hans.md中完全一致。提交说明由此包含下述结构化元素向类库使用者表明其意图fix类型为fix的提交表示在代码库中修复了一个 bug这与语义化版本中的PATCH相对应。feat类型为feat的提交表示在代码库中新增了一个功能这与语义化版本中的MINOR相对应。BREAKING CHANGE在可选的正文或页脚的起始位置带有BREAKING CHANGE:的提交表示引入了破坏性变更这与语义化版本中的MAJOR相对应。破坏性变更可以是任意类型提交的一部分对于fix:、feat:和chore:乃至更多其它的类型而言它都是有效的。除此之外fix:和feat:之外的其它提交类型也都是支持的例如 Angular 约定中推荐使用的docs:、style:、refactor:、perf:、test:、chore:但这些标签在约定式提交规范中并不是强制性的。作用域scope为类型补充上下文可以为提交类型添加一个围在圆括号内的作用域以提供额外的上下文信息。例如feat(parser): add ability to parse arrays.作用域描述的通常是代码库中的某个部分模块、组件、子系统它让读者在扫过提交历史时能立即定位变更影响面。二、为什么需要约定式提交动机与背景规范正文的“介绍”章节解释了这一约定的由来。在软件开发中经验表明 bug 最常由应用间的边界引入单元测试在所测试的交互处于开源维护者知识范围内时工作得很好但在刻画社区里各种有趣而常在预料之外的使用场景时就显得比较糟糕了。任何在升级新依赖 patch 版本后发现应用开始抛出稳定 500 错误流的人都知道可读的提交历史以及理想条件下高质量维护的 CHANGELOG对后续排障有多重要。约定式提交规范提议在提交说明的基础上引入标准化的轻量约定。这个约定与 SemVer 相吻合要求开发者在提交信息中描述新特性、bug 修复和破坏性更新。引入这一约定后我们可以创建一种通用的语言简化在项目边界之间调试的问题——提交信息不再只是写给 git 的注释而是团队成员、下游消费者乃至机器工具都能读懂的结构化数据。三、约定式提交规范完整条文逐条解读规范正文指出文档中的关键词“必须MUST”、“禁止MUST NOT”、“需要REQUIRED”、“应当SHALL”、“不应当SHALL NOT”、“应该SHOULD”、“不应该SHOULD NOT”、“推荐RECOMMENDED”、“可以MAY”和“可选OPTIONAL”应按照 RFC 2119 的描述解释。理解这套强度分级是正确落地规范的前提——必须意味着无条件的强制要求应当/应该意味着正常情况下应遵循、存在合理例外而可以/可选则表示完全自由裁量。规范共十条逐条解读如下每个提交都必须使用类型字段前缀这由一个形如feat或fix的名词组成其后接冒号和空格。注意英文半角冒号与空格是语法的一部分机器解析依赖这一精确格式。当一个提交为应用或类库实现了新特性时必须使用feat类型。这是类型与语义化版本MINOR挂钩的基础。当一个提交为应用修复了 bug 时必须使用fix类型。这是类型与语义化版本PATCH挂钩的基础。可选的作用域字段可以在类型后提供。作用域是描述代码库中某个部分的词组封装在圆括号中形如fix(parser):。描述字段必须紧接在类型或作用域前缀之后。描述是对 pull request 的简短描述例如fix: array parsing issue when multiple spaces were contained in string.。在简短描述之后可以编写更长的提交正文。正文必须起始于描述字段结束的一个空行后空行是分隔描述与正文的语法边界。在正文结束的一个空行后可以编写页脚。页脚应当包含额外的元信息例如它所修复的 issue类似fixes #13, #5。破坏性变更必须在提交的正文或脚注中展示。一个破坏性变更必须包含大写的文本BREAKING CHANGE紧跟冒号和空格。注意此处要求“正文或脚注的起始位置”这一位置约束是 1.0.0-beta.1 阶段与最终版规范差异较大的地方详见下文“规范演进”一节。在BREAKING CHANGE:之后必须提供描述以描述对 API 的变更。例如BREAKING CHANGE: environment variables now take precedence over config files.。在提交说明中可以使用feat和fix之外的类型。这意味着规范鼓励团队扩展自己的类型体系只要保持同样的语法结构即可被工具识别。一份符合规范的完整提交示例将上述条文组合起来一个完整的提交说明长这样feat(parser): add ability to parse arrays Implement recursive descent parsing for nested array literals, handling trailing commas per the project style guide. BREAKING CHANGE: array elements must now be separated by commas fixes #13, #5其中类型为feat、作用域为parser、描述句紧随冒号空格空行后是正文段落再次空行后是页脚——既包含了BREAKING CHANGE:破坏性变更声明也包含了fixes #13, #5的 issue 引用元信息。四、为什么使用约定式提交五大收益规范用五个要点概括了这一约定带来的直接价值自动化生成 CHANGELOG工具可以按类型分组聚合提交信息直接产出可发布的更新日志。基于提交的类型自动决定语义化的版本变更fix升 PATCH、feat升 MINOR、含BREAKING CHANGE升 MAJOR版本号的决策逻辑被完全程序化。向同事、公众与其他利益关系人传达变化的性质任何人在浏览提交历史时都能迅速判断每个提交的意图。触发构建和部署流程CI/CD 系统可以根据提交类型决定是否需要发布、发布何种版本。让人们更容易地探索结构化的提交历史降低贡献项目的难度新贡献者通过类型标签即可快速理解项目演变脉络。五、仓库中的这份规范站点结构、多语言与本地运行本仓库conventionalcommits.org正是用 Hugo 静态站点生成器承载这份规范的官方站点。README.md 说明了仓库布局content目录存放规范的所有版本content/next/存放进行中的草案content/**/index.[lang].md则按语言后缀存放各版本译文——不带语言后缀的是规范原文带后缀的是翻译。本文所依据的 content/v1.0.0-beta.1/index.zh-hans.md 即是 1.0.0-beta.1 版本的中文简体翻译。站点配置见 config.yamltheme: conventional-commits指定了位于 themes/conventional-commits 的主题defaultContentLanguage: en与defaultContentLanguageInSubdir: true决定英文为默认语言且各语言以子目录形式发布。在languages配置块中zh-hans语言条目声明了标题“约定式提交”、描述“一种用于给提交信息增加人机可读含义的规范”并在versions.list中列出了当前展示的版本序列v1.0.0、v1.0.0-beta.4、v1.0.0-beta.3、v1.0.0-beta.2、v1.0.0-beta.1、v1.0.0-beta。站点头部的“Versions / Languages”下拉菜单正是由主题 themes/conventional-commits/layouts/partials/header.html 依据这些配置渲染的页面正文则通过 _default/single.html 将规范内容套入 GitHub 风格 Markdown 样式展示。如果你希望在本机预览这份规范文档仓库提供了 docker-compose.yml安装 docker-compose 后执行docker-compose up站点编译完成后访问http://localhost:1313即可浏览。另外README 还提供了官方徽章badge代码用于在自己的项目 README 中声明“本项目遵循 Conventional Commits 规范”这既是规范在社区中传播的载体也方便贡献者与工具一眼识别项目的提交风格。六、规范演进从 1.0.0-beta.1 到 1.0.0 正式版的关键差异阅读本仓库可以发现1.0.0-beta.1 并非最终形态。对照正式版译文 content/v1.0.0/index.zh-hans.md后续版本主要在以下几处做出了调整理解这些差异有助于你判断项目应采用哪个版本的约定破坏性变更的标记位置beta.1 要求BREAKING CHANGE:位于正文或页脚的起始位置正式版进一步允许在类型(范围)前缀中、冒号之前直接写!如feat!: ...、feat(api)!: ...来标记破坏性变更且!与BREAKING CHANGE:脚注可以二选一。脚注的语法约束正式版将脚注规则细化为 git trailer 惯例——每行脚注须包含一个 token后接:space或space#分隔符再跟值token 中的连字符用-如Acked-by并规定工具实现解析时不得区分大小写、BREAKING-CHANGE是BREAKING CHANGE的同义词。beta.1 阶段对这些细节尚无明确约束。新增“示例”章节与还原revert提交讨论正式版加入了大量可直接复制的示例含!、多行正文与多行脚注的组合并在 FAQ 中补充了还原提交的处理建议推荐revert类型加Refs:脚注。这些差异清楚地表明规范本身也在迭代团队在选型时应以当前目标版本本仓库默认展示 v1.0.0的条文为准。七、FAQ落地过程中的常见问题规范原文以 FAQ 形式回答了实操中几乎必然会遇到的问题全部要点如下。如何处理初始开发阶段的提交说明建议按照已发布的产品那样来处理。一般情况下即便是开发者同事也有人使用你的软件他们会希望知道诸如修复了什么、哪里不兼容等信息。从第一天就遵守规范避免日后重写历史。提交符合一或多种类型时该如何处理回退并尽可能创建多次提交。约定式提交的部分好处是能够促使我们做出更有组织的提交和 PR——一个提交只做一件事类型归属自然清晰。这不会阻碍快速的开发和迭代吗它阻碍的是以杂乱无章的方式快速前进而不是快速本身。它帮助我们在横跨长时间周期、多个项目、多个贡献者时能够保持效率。约定式提交会让开发者受限于提交的类型吗约定式提交鼓励我们更多地使用某些类型的提交比如 fixes。除此之外约定式提交的灵活性也允许你的团队使用自己的类型并随着时间的推移更改这些类型——第 10 条明文允许自定义类型。这和 SemVer 有什么关联呢fix类型提交应当对应到PATCH版本feat类型提交应该对应到MINOR版本带有BREAKING CHANGE的提交不管类型如何都应该对应到MAJOR版本。这一映射是整个自动版本管理工具链如 semantic-release、standard-version 等的运算基础。我对约定式提交做了形如jameswomack/conventional-commit-spec的扩展该如何版本化管理这些扩展呢推荐使用 SemVer 来发布你对于这个规范的扩展规范鼓励创建这些扩展——扩展本身也是软件同样适用规范的分级逻辑。如果我不小心使用了错误的提交类型该怎么办呢分两种情况当你使用了在规范中但错误的类型时如将feat写成了fix在合并或发布这个错误之前建议使用git rebase -i来编辑提交历史而在发布之后根据你使用的工具和流程不同会有不同的清理方案。当使用了不在规范中的类型时如将feat写成了feet在最坏的场景下即便提交没有满足规范也不是世界的终结只是这个提交会被基于规范的工具错过而已——它不会破坏任何东西只是无法被自动分类。所有的贡献者都需要使用约定式提交规范吗并不如果你使用基于 squash 的 Git 工作流主管维护者可以在合并时清理提交信息——这不会对普通提交者产生额外的负担。一种常见的工作流是让 git 系统自动从 pull request 中 squash 出提交向主管维护者提供表单来在合并时输入合适的 git 提交信息。这意味着规范可以只约束合并入口而不给每一位贡献者增加摩擦。八、在真实项目中落地从规范到工具链本仓库的 content/about/index.md 记载了规范与生态工具的渊源规范受 Angular 提交指南启发首版草案是与 conventional-changelog、parse-commit-message、lerna 等工具的维护者协作完成的并持续列出了一系列基于规范的工具例如commitlint校验提交信息是否符合规范、commitizen/cz-cli交互式生成合规提交信息、semantic-release依据提交类型自动决定版本号并发布、standard-version自动版本管理与 CHANGELOG 生成、git-cliffRust 编写的可定制 CHANGELOG 生成器等。从源码结构看规范本身不绑定任何语言或平台只要工具按类型[作用域]: 描述加 RFC 2119 强度语义解析就能在任意技术栈中复用。落地建议可归纳为三步第一步在团队贡献指南中引用规范原文即本仓库中的对应版本文档第二步在 CI 或 git 钩子中接入 commitlint 等校验工具把“必须”级条文变成可执行的检查第三步用 semantic-release 或 standard-version 将fix/feat/BREAKING CHANGE自动映射为 PATCH/MINOR/MAJOR 版本并生成 CHANGELOG。三件事做完提交信息就从“给人看的文字”升级为“驱动发布流程的数据”。结语约定式提交 1.0.0-beta.1 用十条规则定义了一种极简但机器可解析的提交信息语法类型声明变更性质、作用域定位变更范围、正文与页脚承载细节与元信息、BREAKING CHANGE标记破坏性变更。它不强制团队使用哪些类型却强制提交具备一致的骨架——正是这种“结构上的严格、内容上的自由”让它既能被工具自动处理又能长期适应团队自己的演化。本文以 content/v1.0.0-beta.1/index.zh-hans.md 为骨架对照 config.yaml 与主题布局还原了规范的发布形态并对比 content/v1.0.0/index.zh-hans.md 梳理了规范自身的演进脉络。如果你的项目正准备引入这套约定建议以当前正式版 v1.0.0 为准同时以上述 FAQ 与工具链路径作为落地参考。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐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 规范详解用结构化提交消息驱动版本管理与自动化工具 本篇指南以开源仓库 convention文档Conventional Commits 1.0.0-beta 规范全解结构化提交信息与 SemVer 自动化协作指南Conventional Commits 1.0.0 beta 规范全解结构化提交信息与 SemVer 自动化协作指南 本指南以仓库内 content/v1.文档上一篇ToastFish 桌面弹窗背单词摸鱼间隙30秒记住一个新词下一篇CC Switch 在 Windows 上装完打不开跟着症状一步步定位创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考