文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载约定式提交Conventional Commits是一套建立在 Git 提交信息之上的轻量级规范用一套简单清晰的规则帮助团队创建结构化的提交历史并让自动化工具如 CHANGELOG 生成、语义化版本自动升级、构建与发布触发可以在此基础上稳定运行。本文以本仓库content/v1.0.0/index.gr.md希腊语版与英文 1.0.0 正式版内容完全一致为骨架逐条讲解提交信息结构、规范条款、完整示例与高频 FAQ并结合作品仓库的站点源码说明这份规范在开源项目中如何被组织、维护与多语言分发。摘要什么是约定式提交约定式提交规范是一种基于提交信息的轻量级约定。它提供了一组简单易记的规则用于创建显式的提交历史explicit commit history从而让在其之上编写自动化工具变得更加容易。这一约定与语义化版本SemVer相互呼应——通过在提交信息中描述新增特性features、缺陷修复fixes与破坏性变更breaking changes提交历史可以直接映射到版本号的变化。简言之约定式提交让“提交信息”成为人机皆可读的版本元数据来源。提交信息的结构规范要求提交信息遵循如下结构type[optional scope]: description [optional body] [optional footer(s)]即第一行是“类型 可选范围 冒号 描述”的标题行正文body与脚注footer均为可选且各自与上一部分之间用空行分隔。这份结构模板在本仓库中即作为规范正文的一部分被写入 content/v1.0.0/index.gr.md 等各语言版本文档并被 Hugo 站点按 Markdown 渲染展示。核心结构元素提交信息由以下结构化元素组成其目的是向你的库/项目的使用者传达变更意图fix:—— 类型为fix的提交用于修复代码库中的缺陷在语义化版本中对应PATCH补丁版本升级。feat:—— 类型为feat的提交用于引入新特性在语义化版本中对应MINOR次版本升级。BREAKING CHANGE:—— 一个带有BREAKING CHANGE:脚注、或在类型/范围后追加!的提交表示引入了破坏性 API 变更在语义化版本中对应MAJOR主版本升级。需要特别注意的是破坏性变更可以是任意类型提交的一部分不一定非得是feat或fix。其他类型types—— 除fix:与feat:之外允许使用其他类型。例如基于 Angular 约定演进的commitlint/config-conventional推荐了build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等。补充说明这些类型并不被约定式提交规范强制要求除非它们包含 BREAKING CHANGE否则对语义化版本号没有隐式影响。脚注footers—— 除BREAKING CHANGE: description之外还可以提供其他脚注其格式遵循类似 git trailer 格式的约定如Reviewed-by:、Refs:等。范围scope—— 可以为提交类型提供一个 scope用于提供额外的上下文信息写在类型后的圆括号内例如feat(parser): add ability to parse arrays。完整示例以下 6 个示例完整覆盖了规范涉及的主要书写形态均可直接复制使用。带描述与破坏性变更脚注的提交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带 scope 与!的破坏性变更feat(api)!: send an email to the customer when a product is shipped同时使用!与 BREAKING CHANGE 脚注chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.无正文的提交docs: correct spelling of CHANGELOG带 scope 的提交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规范条款Specification逐条解析规范正文使用 RFC 2119 中定义的关键词MUST必须、MUST NOT禁止、REQUIRED要求、SHALL、SHALL NOT、SHOULD应当、SHOULD NOT、RECOMMENDED推荐、MAY可以、OPTIONAL可选。以下 16 条是 1.0.0 版的全部条款提交必须以类型前缀开头类型由一个名词构成如feat、fix其后依次是可选的 scope、可选的!以及必须存在的冒号与空格。feat必须用于新增特性当提交为你的应用或库添加新特性时必须使用类型feat。fix必须用于缺陷修复当提交表示修复你的应用缺陷时必须使用类型fix。scope 可选用scope 可以在类型之后提供必须由描述代码库某一部分的名词构成并放在圆括号内例如fix(parser):。描述必须紧跟冒号与空格描述是对代码变更的简短摘要例如fix: array parsing issue when multiple spaces were contained in string。正文可选用更长的正文可以在简短描述之后提供用于补充代码变更的上下文信息正文必须在描述之后空一行开始。正文为自由格式正文可以是任意数量的段落段落之间用换行分隔。脚注可选用一个或多个脚注可以在正文之后空一行提供。每个脚注必须由关键词 token、分隔符:space或space#以及字符串值组成——这一设计参考了 git trailer 约定。脚注 token 中连字符替代空格脚注的 token 必须使用-代替空白字符例如Acked-by这有助于将脚注部分与多段落的正文区分开。唯一例外是BREAKING CHANGE它也可以作为 token 使用。脚注值可包含空格与换行脚注的值可以包含空格和换行解析过程必须在观察到下一个合法的 token/分隔符组合时终止。破坏性变更必须被标记破坏性变更必须在提交的类型/scope 前缀中或以脚注条目形式标记。作为脚注的格式如果破坏性变更作为脚注必须由大写文本BREAKING CHANGE、冒号、空格和描述组成例如BREAKING CHANGE: environment variables now take precedence over config files。作为前缀的格式如果破坏性变更出现在类型/scope 前缀中必须通过:之前紧邻的!来标记。若使用了!则脚注中的BREAKING CHANGE:可以省略此时应使用提交描述来说明该破坏性变更。允许其他类型除feat与fix之外可以在提交信息中使用其他类型例如docs: update ref docs。大小写约定构成约定式提交的信息单元实现方不得将其视为大小写敏感唯一例外是BREAKING CHANGE必须大写。BREAKING-CHANGE同义当BREAKING-CHANGE作为脚注 token 使用时必须与BREAKING CHANGE同义。值得注意的是条款 9、13、15、16 正是 1.0.0 正式版相对早期 beta 版本的核心收敛点!语法被正式引入、脚注 token 规则被明确、大小写与同义词边界被收紧使得不同工具实现之间的解析行为趋于一致。为什么使用约定式提交规范文档明确列出了五大收益这也是团队引入该规范最常引用的理由自动生成 CHANGELOG基于结构化的提交类型工具可以自动汇总每个版本的变更记录。自动确定语义化版本升级幅度根据落地的提交类型fix→ PATCH、feat→ MINOR、BREAKING CHANGE → MAJOR自动计算下一个版本号。向团队成员、公众和其他利益相关者沟通变更性质提交历史本身就是一份可读的变更公告。触发构建与发布流程CI/CD 可以根据提交类型决定是否发布、发布何种版本。让更多人更容易为项目做贡献结构化的提交历史降低了新人理解项目演进的门槛。常见问题FAQ与最佳实践初始开发阶段如何写提交信息建议从一开始就按“产品已发布”的标准来写提交。通常总会有人哪怕是你的同行开发者在使用你的软件他们需要知道什么被修复了、什么被破坏了。提交标题中的类型用大写还是小写任何一种写法都可以但最好保持一致。提交同时符合多个提交类型时怎么办尽可能回退并拆分成多个提交。约定式提交的价值之一正是推动开发者做出更规整的提交与 PR。这是否会阻碍快速开发与快速迭代它阻止的是“无组织地快速推进”反而帮助你在跨项目、多贡献者的长期场景下保持速度。是否会限制开发者只会使用给定的类型约定式提交鼓励更多特定类型如修复的提交除此之外其灵活性允许你的团队自行定义类型并随时间演进调整。与 SemVer 的关系fix类型提交应翻译为PATCH版本feat类型提交应翻译为MINOR版本包含BREAKING CHANGE的提交无论类型应翻译为MAJOR版本。如何给自己对规范的扩展定版本推荐使用 SemVer 来发布你自己对规范的扩展官方鼓励做这样的扩展。不小心用错了提交类型怎么办用的是规范内但不对的类型如用fix代替feat在合并或发布之前推荐使用git rebase -i编辑提交历史发布之后清理方式取决于你所用的工具与流程。用的是规范外的类型如把feat写成feet最坏情况下也不是世界末日——不合规的提交只是会被基于规范的工具跳过而已。所有贡献者都必须使用规范吗不必。如果使用基于 squash 的 Git 工作流主维护者可以在合并时统一清理提交信息不增加偶然贡献者的负担。常见做法是让 Git 系统自动 squash PR 中的提交并向主维护者弹出表单输入正确的合并提交信息。如何处理 revert还原提交还原代码可能很复杂你是在还原多个提交吗如果还原了一个特性下一个版本应该是 patch 吗规范没有显式定义 revert 行为而是把决定权交给工具作者利用类型与脚注的灵活性来发展自己的还原处理逻辑。规范给出的一条建议是使用revert类型并在脚注中引用被还原的提交 SHArevert: let us never again speak of the noodle incident Refs: 676104e, a215868从仓库源码看规范的站点化落地本仓库conventionalcommits.org就是这份规范的官方站点实现采用 Hugo 静态站点生成器。理解它的组织方式有助于你以同样的模式在自己的团队内维护一份可版本化、多语言的规范文档规范按版本与语言分目录存放所有版本的规范位于content/目录下例如 1.0.0 正式版在content/v1.0.0/每个语言一个文件命名形如index.gr.md希腊语、index.zh-hans.md简体中文、index.md英文默认并各自维护一个由config.yaml中的语言配置驱动的版本下拉菜单。当前仓库的 config.yaml 即包含希腊语gr语言的weight、title、description与站点内锚点导航#περίληψη摘要、#προδιαγραφή规范、#συνεισφέρετε贡献并声明 v1.0.0 为当前版本。渲染链路站点的 单页模板 将各语言 Markdown 正文{{.Content}}嵌入到带markdown-body样式类的文章容器中实现“同一份规范、多语言渲染”。构建流程Makefile 定义了compile-assets进入themes/conventional-commits目录执行npm install npm run build编译 SCSS 与 JS与compile-site执行hugo两个目标前端资源构建脚本定义在 themes/conventional-commits/package.json 中。新增翻译的约定根据 README.md 的说明新增语言需在content/version/下创建index.lang.md并同步在config.yaml中注册该语言——这与本仓库维护 28 种语言版本的实践一致也侧面印证了规范文档本身的“机器可读、便于自动处理”的设计取向。从仓库结构看规范正文始终是唯一事实来源站点层只负责多语言、多版本的呈现与导航这种“规范与展示分离”的组织方式值得希望在团队内部落地约定式提交的工程团队借鉴。结语约定式提交 1.0.0 是一份「小而完整」的规范它只用 16 条条款就定义了提交信息的语法与语义边界为 CHANGELOG 生成、语义化版本计算、CI 发布触发等自动化能力提供了稳定的输入格式。无论是从content/v1.0.0/index.md英文原版、content/v1.0.0/index.gr.md希腊语版还是 config.yaml 中登记的任意语言版本入手你获得的都是同一份权威内容。把它纳入团队提交流程配合 squash 合并与 commitlint 等工具即可在几乎没有额外负担的前提下获得清晰、可机器处理的提交历史。赞分享文档【免费下载链接】conventionalcommits.orgThe conventional commits specification项目地址https://gitcode.com/gh_mirrors/co/conventionalcommits.org点击查看免费下载相关推荐A2UI 仓库的 Gemini 工具链配置解析.gemini/ 目录下的上下文注入、代码审查与风格约束A2UI 仓库的 Gemini 工具链配置解析.gemini/ 目录下的上下文注入、代码审查与风格约束 本篇技术指南以 A2UI 仓库根目录下的 .gemin文档Conventional Commits 1.0.0 规范详解conventionalcommits.org 提交信息约定与自动化落地实践Conventional Commits 1.0.0 规范详解conventionalcommits.org 提交信息约定与自动化落地实践 本指南以 conv文档mold 项目内嵌 oneTBB 的 task_group 动态依赖扩展用 set_task_order 与任务完成转移构建任务间依赖mold 项目内嵌 oneTBB 的 task_group 动态依赖扩展用 set_task_order 与任务完成转移构建任务间依赖 导读 task_gro文档上一篇manga-image-translator模型压缩技术减小体积不降低性能下一篇URL解析实战指南从基础到高级C语言实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考