conventional-commits

Conventional Commits

概述

Conventional Commits 是一项提交信息规范，为创建清晰的提交历史提供了明确的结构。它支持使用自动化工具生成变更日志、确定语义化版本号的升版幅度，并有效传达变更内容。

核心原则：每条提交信息都遵循结构化格式，清晰传达变更的类型和范围。

提交信息结构

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

快速参考

要素	必需性	格式	用途
类型	✅ 是	feat、fix 或自定义类型	表明变更的性质
范围	❌ 可选	括号：(parser)	提供补充上下文
破坏性变更	❌ 可选	类型/范围后加 !	表明存在破坏性变更
描述	✅ 是	简短摘要	简要描述变更
正文	❌ 可选	自由格式的段落	详细说明
页脚	❌ 可选	Token: value 格式	元数据（例如 BREAKING CHANGE:）

提交类型

标准类型

• feat：新功能（对应 SemVer 中的 MINOR）
• fix：错误修复（对应 SemVer 中的 PATCH）

其他常见类型

• build：构建系统或依赖项变更
• chore：维护任务，不涉及生产代码变更
• ci：CI 配置变更
• docs：仅涉及文档的变更
• hotfix：直接应用于生产环境、绕过常规开发工作流的紧急错误修复（对应 SemVer 中的 PATCH）
• perf：性能改进
• refactor：代码重构，不改变行为
• style：代码风格变更（格式调整、缺少分号等）
• test：添加或更新测试

破坏性变更

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

1. 在类型/范围前缀中：在冒号前添加 !

   feat!: remove deprecated API
   feat(api)!: change authentication method
   

2. 在页脚中：使用 BREAKING CHANGE: 标记

   feat: add new authentication system
   
   BREAKING CHANGE: Old authentication tokens are no longer valid
   

示例

基本功能提交

feat: add user authentication endpoint

Implement JWT-based authentication with login and token validation

带范围的功能提交

feat(auth): implement password reset flow

Add forgot password endpoint and email notification system

错误修复

fix(parser): correct array parsing with multiple spaces

Handle edge case where strings contained multiple consecutive spaces

破坏性变更（前缀）

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All v1 API endpoints have been removed. Migrate to v2.

破坏性变更（页脚）

feat: update database schema

BREAKING CHANGE: Environment variables now take precedence over config files

文档

docs: update API reference for authentication endpoints

重构

refactor(auth): extract token validation to separate module

Improve code organization and testability

性能

perf(queries): optimize database query for user lookup

Reduce query time from 500ms to 50ms by adding index

紧急修复

安全紧急修复

hotfix(auth): fix critical security vulnerability in token validation

Immediate fix for CVE-2024-XXXX. Patch token validation to prevent unauthorized access.

数据库紧急修复

hotfix(db): fix connection pool exhaustion causing service outage

Emergency patch to increase pool size and add connection timeout. Applied directly to production to restore service.

支付紧急修复

hotfix(payment): fix incorrect currency conversion in checkout

Critical bug causing incorrect charges. Immediate fix applied to prevent financial impact.

API 紧急修复

hotfix(api): fix null pointer exception in user endpoint

Emergency fix for production crash. Bypassed normal deployment process.

性能紧急修复

hotfix(cache): fix memory leak causing server crashes

Immediate fix for production instability. Applied hotfix to prevent service degradation.

数据完整性紧急修复

hotfix(data): fix corrupted data migration affecting user accounts

Emergency fix applied directly to production database to prevent data loss.

常见错误

❌ 缺少冒号和空格

feat add authentication

✅ 正确：

feat: add authentication

❌ 类型使用大写字母

FEAT: add authentication

✅ 正确：

feat: add authentication

❌ 描述过长

feat: add user authentication with JWT tokens, password hashing, session management, and email verification

✅ 正确：

feat(auth): implement JWT-based authentication

Add login endpoint, password hashing, session management, and email verification

❌ 使用了错误的类型

fix: add new feature for user dashboard

✅ 正确：

feat: add user dashboard

❌ 未标明破坏性变更

feat(api): remove deprecated endpoints

✅ 正确：

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: All v1 endpoints have been removed

❌ 范围未使用括号

feat auth: implement login

✅ 正确：

feat(auth): implement login

工作流指南

创建提交时

1. 确定类型：这是功能、修复还是其他类型？
   • 对于直接应用于生产环境、绕过常规开发工作流的紧急修复，使用 hotfix
   • 对于常规开发工作流中的常规错误修复，使用 fix
2. 确定范围（可选）：代码库中的哪些部分受到影响？
3. 检查是否存在破坏性变更：此变更是否会破坏现有功能？
4. 撰写简洁描述：尽可能控制在 72 个字符以内
5. 按需添加正文：提供上下文、动机或详细信息
6. 适用时添加页脚：添加破坏性变更、引用等信息

描述最佳实践

• 使用祈使语气：“add feature”，而不是“added feature”或“adds feature”
• 结尾不要加句号
• 保持简洁（理想长度为 50–72 个字符）
• 聚焦于发生了什么变化，而非为什么变化（原因写在正文中）

正文最佳实践

• 与描述之间空一行
• 说明变更背后的“原因”
• 提供上下文或背景
• 引用相关议题或 PR

语义化版本关联

提交类型	SemVer 影响
fix	PATCH（1.0.0 → 1.0.1）
hotfix	PATCH（1.0.0 → 1.0.1）
feat	MINOR（1.0.0 → 1.1.0）
BREAKING CHANGE	MAJOR（1.0.0 → 2.0.0）
其他类型	不会自动提升版本号

验证清单

最终确定提交消息之前，请确认：

• 类型使用小写且有效
• 类型/范围后跟冒号和空格
• 描述简洁且使用祈使语气
• 正确标明破坏性变更
• 正文前空一行（如果有正文）
• 页脚标记使用连字符（例如 BREAKING CHANGE，而不是 BREAKING_CHANGE）
• 标题未超过 120 个字符（如果团队标准有此要求）

特殊情况

回滚提交

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

一个功能对应多个提交

如果一个提交符合多种类型，请尽可能拆分为多个独立提交：

feat(auth): add login endpoint
test(auth): add login endpoint tests
docs(auth): update API documentation for login

与工具集成

Conventional Commits 支持：

• 自动生成变更日志：工具会解析提交历史
• 语义化版本：根据提交类型自动提升版本号
• 发行说明：从提交中提取功能和修复
• 构建触发器：针对不同提交类型执行不同的构建流程

其他资源

• reference.md — 官方规范、提交类型、SemVer 关联、工具 — 可索引
• 官方规范：https://www.conventionalcommits.org/en/v1.0.0/

规范参考

此技能基于官方的 Conventional Commits 规范 v1.0.0。

此技能中的所有规则、示例和指南均遵循官方规范。完整规范、示例和常见问题解答请参阅官方文档。