名称： conventional-commits
描述： 使用 Conventional Commits 规范格式化提交信息。适用于创建提交、编写提交信息，或当用户提及提交、git 提交或提交信息时。确保提交遵循自动化工具、变更日志生成和语义化版本控制的标准格式。
许可证： MIT
元数据：
author: github.com/bastos
version: "2.0"

Conventional Commits

根据 Conventional Commits 规范格式化所有提交信息。这有助于自动化生成变更日志、进行语义化版本控制，并改善提交历史记录。

格式结构

<类型>[可选范围]: <描述>

[可选正文]

[可选脚注]

提交类型

必需类型

• feat: - 新增功能（对应语义化版本中的 MINOR 版本）
• fix: - 修复错误（对应语义化版本中的 PATCH 版本）

常用附加类型

• docs: - 仅文档变更
• style: - 代码风格变更（格式化、缺少分号等）
• refactor: - 代码重构，不涉及错误修复或新功能
• perf: - 性能改进
• test: - 添加或更新测试
• build: - 构建系统或外部依赖变更
• ci: - CI/CD 配置变更
• chore: - 其他不修改源代码或测试文件的变更
• revert: - 撤销之前的提交

范围

可选的范围提供了关于代码库特定部分的额外上下文信息：

feat(解析器): 添加解析数组的能力
fix(认证): 解决令牌过期问题
docs(自述文件): 更新安装说明

描述

• 必须紧跟在类型/范围后的冒号和空格之后
• 使用祈使语气（例如“添加功能”，而非“已添加功能”或“添加了功能”）
• 首字母不要大写
• 结尾不要使用句号
• 保持简洁（通常为 50-72 个字符）

正文

• 可选的详细描述，提供额外上下文
• 必须在描述后空一行开始
• 可以包含多个段落
• 解释变更的“内容”和“原因”，而非“方式”

破坏性变更

可以通过以下两种方式标识破坏性变更：

1. 在类型/范围中使用 !

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

2. 使用 BREAKING CHANGE 脚注

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

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

3. 两种方法结合使用

chore!: 放弃对 Node 6 的支持

BREAKING CHANGE: 使用了 Node 6 不支持的 JavaScript 特性。

示例

简单功能

feat: 添加用户认证

带范围的功能

feat(认证): 添加 OAuth2 支持

带正文的错误修复

fix: 防止请求竞争

引入请求 ID 和对最新请求的引用。忽略来自非最新请求的传入响应。

移除用于缓解竞争问题但现已过时的超时设置。

破坏性变更

feat!: 迁移至新的 API 客户端

BREAKING CHANGE: API 客户端接口已变更。所有方法现在返回 Promise 而非使用回调。

文档更新

docs: 更正 CHANGELOG 的拼写

多段落正文带脚注

fix: 防止请求竞争

引入请求 ID 和对最新请求的引用。忽略来自非最新请求的传入响应。

移除用于缓解竞争问题但现已过时的超时设置。

Reviewed-by: Z
Refs: #123

指导原则

1. 始终使用类型 - 每个提交必须以类型开头，后跟冒号和空格
2. 使用祈使语气 - 写作时想象在完成句子“如果应用，此提交将...”
3. 具体明确 - 描述应清晰传达变更内容
4. 保持专注 - 每个提交只包含一个逻辑变更
5. 在有用时使用范围 - 范围有助于在代码库内对变更进行分类
6. 记录破坏性变更 - 始终清晰地标识破坏性变更

语义化版本控制对应关系

• fix: → PATCH 版本升级 (1.0.0 → 1.0.1)
• feat: → MINOR 版本升级 (1.0.0 → 1.1.0)
• BREAKING CHANGE → MAJOR 版本升级 (1.0.0 → 2.0.0)

使用时机

在以下情况下使用此格式：
- 所有 git 提交
- 生成提交信息
- 拉取请求合并提交
- 当用户询问提交信息或 git 提交时

应避免的常见错误

❌ Added new feature (过去时，首字母大写)
✅ feat: add new feature (祈使语气，小写)

❌ fix: bug (过于模糊)
✅ fix: resolve null pointer exception in user service

❌ feat: add feature (冗余)
✅ feat: add user profile page

❌ feat: Added OAuth support. (过去时，句号)
✅ feat: add OAuth support