本文介绍Conventional Commits 1.0.0 (opens new window)规范。

摘要

Conventional Commits规范是一种轻量级的提交消息约定。

它提供了一套简单的规则，用于创建明确的提交历史记录；这使得编写自动化工具更加容易。

此规范与SemVer (opens new window)紧密结合，通过描述提交消息中的特性、修复和重大更改来实现版本管理。

提交消息应按照以下格式构建：

<type>[可选范围]: <描述>

[可选正文]

[可选页脚]

提交包含以下结构元素，以向库的使用者传达意图：

1. fix: 类型为fix的提交修复代码库中的错误（这对应于语义化版本控制中的PATCH (opens new window)）。
2. feat: 类型为feat的提交引入代码库中的新功能（这对应于语义化版本控制中的MINOR (opens new window)）。
3. BREAKING CHANGE: 如果提交的页脚包含BREAKING CHANGE:或在类型/范围后附加!，则表示引入了破坏性API更改（这对应于语义化版本控制中的MAJOR (opens new window)）。破坏性更改可以是任何类型的提交的一部分。
4. 其他类型：除了fix:和feat:之外，还可以使用其他类型，例如@commitlint/config-conventional (opens new window)（基于Angular约定 (opens new window)）推荐的build:、chore:、ci:、docs:、style:、refactor:、perf:、test:等。
5. 除BREAKING CHANGE: <描述>之外的其他页脚也可以提供，并遵循类似于git trailer format (opens new window)的约定。

其他类型不受Conventional Commits规范强制要求，也不会在语义化版本控制中产生隐式影响（除非它们包括破坏性更改）。可以通过括号提供范围，以提供更多上下文信息，例如feat(parser): 添加解析数组的能力。

常见的type：

• build: 构建系统或外部依赖的更改。
• chore: 日常维护任务，不影响代码功能。
• ci: 持续集成相关文件或配置的更改（如 GitHub Actions、Travis CI）。
• docs: 文档更新或修改。
• feat: 新功能的添加。
• fix: 修复 Bug。
• perf: 性能优化。
• refactor: 代码重构，不改变功能。
• revert: 回滚之前的提交。
• style: 样式或格式调整，不影响代码逻辑（如缩进、空格）。
• test: 测试相关的更改或新增测试用例。

常见的 scope：

• auth: 认证相关模块
• user: 用户管理模块
• api: API 相关更改
• config: 配置文件或设置
• deps: 依赖项更新
• dashboard: 仪表盘或控制台
• header: 页面头部组件
• login: 登录功能或页面
• search: 搜索功能
• core: 核心逻辑或全局功能

示例

包含描述和破坏性更改页脚的提交消息

feat: 允许提供的配置对象扩展其他配置

BREAKING CHANGE: 配置文件中的 extends 键现在用于扩展其他配置文件

使用!标记破坏性更改的提交消息

feat!: 在产品发货时向客户发送电子邮件

带有范围和!标记破坏性更改的提交消息

feat(api)!: 在产品发货时向客户发送电子邮件

同时包含!和破坏性更改页脚的提交消息

chore!: 丢弃对节点 6 的支持

BREAKING CHANGE: 使用 Node 6 中不可用的 JavaScript 功能。

不带正文的提交消息

docs: CHANGELOG 的正确拼写

带有范围的提交消息

feat(lang): 添加波兰语

包含多段正文和多个页脚的提交消息

fix: 防止请求争用

引入请求 ID 和对 latest 请求的引用。解雇来自 latest request 以外的传入响应。

删除了用于缓解赛车问题的超时，但现在已经过时了。

Reviewed-by: Z
Refs: #123

规范

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按RFC 2119 (opens new window)中的描述进行解释。

1. 提交必须以前缀类型开头，该类型由名词组成，如feat、fix等，后跟可选范围、可选!以及必需的冒号和空格。
2. 当提交添加新功能到应用程序或库时，必须使用类型feat。
3. 当提交代表应用程序的错误修复时，必须使用类型fix。
4. 可以为类型提供范围。范围必须由一个描述代码库部分的名词组成，并用括号包围，例如fix(parser):。
5. 描述必须紧随类型/范围前缀后的冒号和空格。描述是对代码更改的简短总结，例如fix: String 中包含多个空格时的数组解析问题。
6. 可以在简短描述后提供较长的提交正文，提供有关代码更改的更多上下文信息。正文必须从描述后的一行空白开始。
7. 提交正文是自由形式的，可以包含任意数量的新行分隔段落。
8. 在正文后的一行空白后可以提供一个或多个页脚。每个页脚必须由一个单词标记组成，后跟:或#分隔符，再跟一个字符串值（这受到git trailer convention (opens new window)的启发）。
9. 页脚标记必须用-替换空白字符，例如Acked-by（这有助于区分页脚部分和多段正文）。BREAKING CHANGE作为标记时例外。
10. 页脚值可以包含空格和换行符，解析必须在观察到下一个有效的页脚标记/分隔符对时终止。
11. 破坏性更改必须在提交的类型/范围前缀中指示，或者作为页脚条目。
12. 如果作为页脚包含，破坏性更改必须由大写字母BREAKING CHANGE组成，后跟冒号、空格和描述，例如BREAKING CHANGE: 环境变量现在优先于配置文件。
13. 如果包含在类型/范围前缀中，破坏性更改必须由!立即在:之前指示。如果使用!，则可以从页脚部分省略BREAKING CHANGE:，并且提交描述应用于描述破坏性更改。
14. 提交消息中可以使用其他类型，例如docs: update ref docs.。
15. 实现者不应将构成常规提交的信息单元视为大小写敏感，但BREAKING CHANGE必须大写。
16. 当用作页脚标记时，BREAKING-CHANGE必须与BREAKING CHANGE同义。

为什么使用Conventional Commits？

• 自动生成CHANGELOG。
• 自动确定语义版本提升（基于提交的类型）。
• 向团队成员、公众和其他利益相关者传达更改性质。
• 触发构建和发布过程。
• 通过允许人们探索更结构化的提交历史，使人们更容易贡献到您的项目。

常见问题解答

初始开发阶段如何处理提交消息？

我们建议您像已经发布产品一样继续进行。通常有人，即使是您的软件开发人员同事，也在使用您的软件。他们会想知道哪些问题已修复，哪些会破坏等。

提交标题中的类型是大写还是小写？

可以使用任何大小写，但最好保持一致。

如果提交符合多个提交类型怎么办？

尽可能回退并制作多个提交。Conventional Commits的部分好处在于其驱动我们制作更有组织的提交和PR的能力。

这是否阻碍了快速开发和快速迭代？

它阻止了无序的快速移动。它帮助您能够在多个项目中长期快速移动，即使有不同贡献者也是如此。

Conventional Commits是否会限制开发者制作的提交类型，因为他们只会考虑提供的类型？

Conventional Commits鼓励我们制作某些类型的提交，例如修复。除此之外，Conventional Commits的灵活性允许您的团队制定自己的类型，并随着时间改变这些类型。

这与SemVer有何关系？

fix类型的提交应转换为PATCH发布。feat类型的提交应转换为MINOR发布。无论类型如何，包含BREAKING CHANGE的提交应转换为MAJOR发布。

如何为Conventional Commits规范的扩展版本？例如@jameswomack/conventional-commit-spec？

我们建议使用SemVer发布对此规范的扩展（并鼓励您制作这些扩展！）

如果不小心使用了错误的提交类型怎么办？

当使用了属于规范但不是正确类型的类型时，例如fix而不是feat

在合并或发布错误之前，我们建议使用git rebase -i编辑提交历史。发布后，清理方式将根据您使用的工具和流程而异。

当使用了不属于规范的类型时，例如feet而不是feat

最坏的情况下，如果提交不符合Conventional Commits规范，世界末日不会到来。这只是意味着该提交将被基于规范的工具忽略。

所有贡献者都需要使用Conventional Commits规范吗？

不需要！如果您使用Git上的squash工作流，主维护者可以在合并时清理提交消息——不会增加临时提交者的负担。常见的工作流是让您的Git系统自动压缩来自拉取请求的提交，并为主维护者提供输入正确的Git提交消息的表单。

Conventional Commits如何处理revert提交？

回滚代码可能很复杂：您是在回滚多个提交吗？如果回滚了一个特性，下一个发布应该是补丁吗？

Conventional Commits没有明确努力定义回滚行为。而是留给工具作者使用类型和页脚的灵活性来开发他们处理回滚的逻辑。

一个建议是使用revert类型，并在页脚中引用正在回滚的提交SHA：

revert: 让我们永远不要再谈论 Noodle 事件

Refs: 676104e, a215868

祝你变得更强!