文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载本指南以开源仓库 conventionalcommits.org 中 content/v1.0.0-beta.3/index.ru.mdConventional Commits 规范 1.0.0-beta.3 版本俄语译本为骨架完整讲解该规范的提交信息结构、11 条 MUST/SHOULD/MAY 规范条文、与语义化版本SemVer的对应关系以及团队落地实践中的常见问题。阅读本文后你将能写出符合规范的提交信息理解其背后的设计意图并掌握如何在日常开发、版本发布与自动化工具CHANGELOG 生成、自动版本号提升、构建发布触发中应用这套约定。一、规范概览在提交信息之上的一层轻量约定Conventional Commits 是一个建立在提交信息commit messages之上的简单约定。它提供了一套易于遵循的规则用于创建明确可读的提交历史从而更容易在其之上构建自动化工具。该约定与 SemVer语义化版本相互配合通过提交信息来描述新增功能features、缺陷修复fixes以及破坏性变更breaking changes。规范本身并不强制要求提交信息中必须包含正文body或脚注footer仅要求对提交的**标题行subject**使用简单的格式。仓库根目录下的 README.md 明确指出This repo is the home of the Conventional Commits specification即本仓库正是该规范官方站点的源码所在。站点采用 HUGO 静态站点生成器构建规范正文按版本存放于content/目录各版本支持多种语言翻译例如本指南对应的俄语版本即存放于 content/v1.0.0-beta.3/index.ru.md。二、提交信息的标准结构规范要求提交信息采用如下结构type[optional scope]: description [optional body] [optional footer]各结构元素解读如下元素是否可选说明type必填提交的类型必须是名词如feat、fix等[optional scope]可选用圆括号包裹的上下文范围如parser:必填类型及可选 scope之后必须跟冒号和空格description必填对代码变更的简短描述紧随冒号和空格之后[optional body]可选更长的正文补充变更的上下文信息与描述之间以空行分隔[optional footer]可选脚注用于放置任务编号issue 引用、BREAKING CHANGE 等元信息与正文之间以空行分隔三个核心结构元素的语义提交信息中包含以下结构元素用于向你的库的使用者传达意图fix:—fix类型的提交修复代码库中的缺陷bug对应语义化版本中的PATCH补丁版本。feat:—feat类型的提交为代码库引入新功能feature对应语义化版本中的MINOR次版本。BREAKING CHANGE:— 在可选正文body或脚注footer开头包含文本BREAKING CHANGE:的提交引入破坏 API 兼容性的变更对应语义化版本中的MAJOR主版本。BREAKING CHANGE 可以成为任何_类型_提交的一部分。其他类型与推荐类型除fix:和feat:之外的提交类型同样允许使用。例如基于 The Angular convention 的 commitlint/config-conventional 推荐使用chore:、docs:、style:、refactor:、perf:、test:等。规范同时推荐使用improvement类型用于表示对现有实现进行改进但既不新增功能也不修复缺陷的提交。请注意这些补充类型并非本规范强制要求的除非它们包含 BREAKING CHANGE否则在语义化版本SemVer中不产生任何隐式影响。Scope上下文范围可以在提交类型旁边声明上下文scope以提供额外的上下文信息它必须被包含在圆括号中例如feat(parser): add ability to parse arrays上例中parser即 scope表明该变更作用于解析器模块。三、完整示例以下示例均来自 content/v1.0.0-beta.3/index.ru.md 的 Examples 章节可直接作为日常提交的模板参考。示例一包含描述与正文中破坏性变更的提交feat: allow provided config object to extend other configs BREAKING CHANGE: extends key in config file is now used for extending other config files示例二无正文的提交docs: correct spelling of CHANGELOG示例三带上下文范围scope的提交feat(lang): add polish language示例四使用可选的缺陷编号的修复提交fix: correct minor typos in code see the issue for details on the typos fixed closes issue #12其中脚注closes issue #12即用于引用被该提交解决的缺陷编号。四、规范正文Specification11 条权威条文本规范中的关键词 MUST必须、MUST NOT禁止、REQUIRED要求、SHALL应当、SHALL NOT不应当、SHOULD应该、SHOULD NOT不应该、RECOMMENDED推荐、MAY可以、OPTIONAL可选均按 RFC 2119 中的定义解释。逐条解读如下提交必须MUST以类型开头类型由名词构成如feat、fix等其后跟一个冒号和一个空格。feat类型必须MUST用于新增功能当提交为你的应用或库添加新功能时使用。fix类型必须MUST用于缺陷修复当提交代表对你的应用或库进行缺陷修复时使用。上下文范围scope可以MAY跟在类型之后scope 是用圆括号括起来的、描述代码库某一区域的短语例如fix(parser):。描述必须MUST紧跟类型/scope 前缀之后描述是对代码变更的简短概括例如fix: array parsing issue when multiple spaces were contained in string.正文body可以MAY在简短描述之后提供用于补充代码变更的额外上下文信息正文必须MUST在描述之后空一行开始。脚注footer可以MAY在正文之后空一行提供脚注应该SHOULD包含关于代码变更的额外问题引用例如它所修复的问题如Fixes #13。破坏性变更必须MUST在提交的脚注或正文部分的最开始处指明破坏性变更必须MUST由大写文本BREAKING CHANGE加冒号和空格组成。在BREAKING CHANGE:之后必须MUST提供描述说明 API 发生了什么变化例如BREAKING CHANGE: environment variables now take precedence over config files.脚注必须MUST只包含BREAKING CHANGE、外部链接、问题引用以及其他元信息。除feat和fix之外的类型可以MAY在提交信息中使用。从仓库结构看规范的版本化发布方式从仓库结构可以推断本仓库对规范的发布本身也遵循了版本化与迭代演进的思路config.yaml 中的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六个已发布版本每个版本在content/下都有独立的目录而 README.md 说明content/next/存放的是所有变更应该SHOULD提交的地方即下一个版本的草案。beta.3 与后续 beta.4 / 1.0.0 的差异例如 beta.4 引入了!标记以强化对破坏性变更的提示并补充了 case-sensitivity 相关条文可以在 content/v1.0.0-beta.4/index.md 与 content/v1.0.0/index.md 中对比查看。五、为什么使用 Conventional Commits规范明确列出的收益包括自动生成 CHANGELOG基于结构化的提交历史工具可以自动汇总各版本的变更清单。自动确定语义化版本号提升semantic version bump根据合并的提交类型fix→ PATCH、feat→ MINOR、BREAKING CHANGE → MAJOR自动决定下一个版本号。向队友、公众和其他利益相关方传达变更的性质结构化的提交信息本身就是一种沟通语言。触发构建与发布流程自动化工具可以依据提交类型决定是否触发 CI 构建、打包和发布。降低贡献门槛结构化的提交历史让人们更容易参与你的项目——新贡献者可以快速读懂项目演进脉络。六、FAQ团队落地中的常见问题1. 初始开发阶段应该怎么写提交信息建议从一开始就按照产品已经发布的方式写提交信息。通常总有人——哪怕只是你的同行开发者——在使用你的代码他们需要知道什么被修复了、什么被破坏了等。2. 提交标题中的类型应该大写还是小写任何大小写形式都可以使用但最好在整个提交历史中保持一致。3. 如果一个提交同时符合多种提交类型怎么办尽可能返回去拆分成多个提交。Conventional Commits 的收益之一正是它促使我们做出更组织化的提交和 PR。4. 这难道不会阻碍快速开发与快速迭代吗它阻碍的是以无序的方式快速前进而能帮助你在长期内、跨多个项目、与不同贡献者协作时依然保持高速。5. 会不会让开发者因为要考虑类型而限制提交类型的多样性Conventional Commits 鼓励我们多做出某些特定类型的提交例如fix。除此之外它的灵活性允许你的团队创造自己的类型并随时间演进这些类型。6. 它如何与 SemVer 规则关联fix类型的提交应反映在PATCH版本发布中feat类型的提交应反映在MINOR版本发布中无论类型如何只要提交的正文或脚注中包含BREAKING CHANGE都应反映在MAJOR版本发布中。7. 如何对规范扩展进行版本管理例如jameswomack/conventional-commit-spec建议使用 SemVer 来发布你对本规范的扩展并且鼓励你做出这些扩展。8. 不小心用错了提交类型怎么办分两种情况用了规范中的类型但用错了例如用fix代替feat在合并或发布之前建议使用git rebase -i编辑提交历史发布之后清理方式将取决于你使用的工具和流程。用了规范之外的类型例如把feat拼写成feet这不是世界末日它只是意味着基于本规范的自动化工具会漏掉这条提交。9. 所有贡献者都必须使用本规范吗不需要如果你采用基于 Git squash 合并的工作流主导维护者可以在合并时清理提交信息——不会给普通贡献者增加任何负担。常见的做法是让 Git 系统在合并 pull request 时自动 squash 所有提交并向维护者展示一个表单由维护者填写规范的合并提交信息。七、在官方站点中的呈现方式规范文档在本仓库中通过 HUGO 主题 themes/conventional-commits 渲染为官方站点页面。从 themes/conventional-commits/layouts/_default/single.html 可以看到规范正文以.Content形式注入到markdown-body容器中config.yaml 中俄语ru语言配置的title为Соглашение о коммитах提交约定description为Простое соглашение о том, как нужно писать сообщения коммитов关于如何编写提交消息的简单约定并配置了#главное概览、#спецификация规范等锚点导航。站点头部header.html提供了 Versions 与 Languages 下拉切换方便读者在各版本和各语言翻译之间切换阅读。如果你希望本地预览该规范站点仓库 README.md 提供了基于 docker-compose 的方式在安装 docker-compose 后于仓库根目录执行docker-compose up编译完成后访问http://localhost:1313即可查看。若需为仓库新增一种语言的翻译可在content/对应版本目录下创建index.[lang].md文件并在 config.yaml 的languages中注册该语言。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐Conventional Commits 1.0.0-beta 规范全解结构化提交信息与 SemVer 自动化协作指南Conventional Commits 1.0.0 beta 规范全解结构化提交信息与 SemVer 自动化协作指南 本指南以仓库内 content/v1.文档TRL基于 Transformers 的强化学习后训练库——从 SFT 到 GRPO/DPO 的完整实战指南TRL基于 Transformers 的强化学习后训练库——从 SFT 到 GRPO/DPO 的完整实战指南 TRLTransformers Reinfor文档Conventional Commits约定式提交1.0.0-beta.4 规范详解结构化提交信息、破坏性变更与 SemVer 自动化Conventional Commits约定式提交1.0.0 beta.4 规范详解结构化提交信息、破坏性变更与 SemVer 自动化 本文是 conve文档上一篇探索未来科技LMFlow —— 高效开放的模型微调工具箱下一篇【亲测免费】 推荐开源项目Notesnook - 您的端到端加密笔记守护者创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考