Conventional Commits规范

原创于 2025-10-30 15:03:09 发布 · 878 阅读

23 ·

CC 4.0 BY-SA版权

文章标签：

#github #git #bash

【投稿赢 iPhone 17】「我的第一个开源项目」故事征集：用代码换C位出道！ 10w+人浏览 1.7k人参与

Summary

Conventional Commits 规范是在提交消息之上建立的轻量级约定。它提供了一套简单的规则来创建明确的提交历史记录，从而简化了基于此的自动化工具的编写。该约定与语义化版本控制（SemVer）相契合，通过在提交消息中描述新增功能、修复和重大变更来实现。

Structure

一个规范的 Commit Message 分为三个部分：标题 (Header)、正文 (Body) 和 页脚 (Footer)。

<type>[optional scope]: <description> // Header

[optional body] // Body

[optional footer(s)] // Footer

Header

这是必须的，它本身包含三个部分：

type (类型): 必填，说明 commit 的类别。
- feat: 新功能 (feature)
- fix: 修复 bug
- perf: 性能优化 (performance improvement)
- refactor: 重构 (既不是修 bug 也不是加功能的代码改动)
- style: 格式调整 (不影响代码运行的变动，如空格、分号)
- docs: 文档 (documentation)
- test: 增加测试
- chore: 构建过程或辅助工具的变动 (如修改 .gitignore)
scope (范围): 可选，用于说明 commit 影响的范围 (如：parser, auth, ui)。
description (描述): 必填，简短描述。
- 使用动词开头，用现在时（例如，“使用XXX，修复… ”而不是“使用了**，**修复了…”）
- 结尾不加句号

Body

这是可选的，是你“具体做了哪些改动，为什么”。

在标题行下空一行。
详细说明代码变动的动机 (Why) 和具体内容 (What)。
使用 - 或 * 来创建项目符号列表。

Footer

这是 可选的，通常用于两种情况：

重大变更 (BREAKING CHANGE): 如果当前代码与上一个版本不兼容。
关闭 Issue: Fixes #123, Closes #456

Specification

提交必须以类型作为前缀，类型由名词、 feat 、 fix 等组成，后跟可选的作用域、可选的感叹号 ! 以及必需的终止冒号和空格。
类型之后可以指定作用域。作用域必须由一个名词组成，该名词描述代码库中的某个部分，并用括号括起来，例如： fix(parser):
类型/作用域前缀后的冒号和空格后必须紧跟描述。描述是对代码更改的简短总结，例如： 修复：字符串中包含多个空格时数组解析出现的问题 。
简短描述之后可以添加更长的提交主体，以提供有关代码变更的更多上下文信息。主体必须在描述之后的一个空行处开始。
提交内容是自由格式的，可以由任意数量的以换行符分隔的段落组成。
正文之后可以空一行提供一个或多个页脚。每个页脚必须包含一个单词标记，后跟一个 :<space> 或 <space># 分隔符，再后跟一个字符串值（此设计灵感来源于……） git 尾部约定）。
页脚标记必须使用连字符 - 代替空格字符，例如 Acked-by （这有助于将页脚部分与多段落正文区分开来）。但 BREAKING CHANGE 除外，它也可以用作标记。
页脚的值可以包含空格和换行符，解析必须在遇到下一个有效的页脚标记/分隔符对时终止。
必须在提交的类型/范围前缀中注明重大变更，或者在页脚中注明。
如果以页脚形式包含重大变更通知，则必须以大写字母“BREAKING CHANGE”开头，后跟冒号、空格和描述，例如： 重大变更：环境变量现在优先于配置文件 。
如果包含在类型/范围前缀中，则必须用以下方式指示重大更改： ! 紧跟在 : 之前。如果使用 ! ，则 BREAKING CHANGE: 可以从页脚部分省略，并且提交描述应用于描述重大变更。
提交消息中可以使用 feat 和 fix 以外的类型，例如： docs: update ref docs。
构成常规提交的信息单元必须由实施者区分大小写，但“重大变更”必须大写。
当用作页脚标记时，BREAKING-CHANGE 必须与 BREAKING CHANGE 同义。

Examples

perf(engine): 优化工作线程逻辑并改进粒子遍历

- 修复了 `workTime` 在实际工作执行前被错误计算和休眠的问题，确保线程在正确的时间点休眠。
- 将粒子列表的 `removeAll` 操作替换为使用迭代器 (Iterator) 进行遍历和移除。

Refs #15

这个页脚 Refs #15 的意思是： “这次性能优化和 #15 号 Issue (关于卡顿的那个) 是相关的，但这个 commit 可能还没有完全解决它，所以先不要关闭那个 Issue。”

FAQ

如果提交符合多种提交类型，我该怎么办？

返回并进行多次提交。常规提交的好处之一是它能够促使我们进行更有条理的提交和 PR。

我应该如何根据“常规提交规范”为我的扩展添加版本号，例如 `@jameswomack/conventional-commit-spec` ？

使用 SemVer 发布您自己对此规范的扩展。

如果我意外使用了错误的提交类型该怎么办？

当你使用了符合规范但类型不正确的类型时，例如使用了 `fix` 而不是 `feat`

在合并或发布错误代码之前，使用 git rebase -i 编辑提交历史。发布后，清理工作会根据您使用的工具和流程而有所不同。

当你使用不符合规范的类型时，例如 `feet` 代替 `feat`

最坏的情况下，即使提交的代码不符合常规提交规范，也并非世界末日。这仅仅意味着基于该规范的工具将无法识别该提交。