common-conventional-commits

common-conventional-commits

所有提交消息都遵循 Conventional Commits 1.0.0 规范，生成结构化、一致的提交历史，便于自动化工具处理和清晰沟通。

适用场景

在以下情况使用此技能：

• 编写提交消息（通过 git commit、交互式变基、压缩提交等）
• 向用户建议提交消息
• 审查或更正提交消息
• 将工作拆分为多个提交并决定如何描述每个提交

说明

1. 提交消息结构

每条提交消息都必须遵循以下格式：

<type>[(<ticket-number>)]: <description>

[optional body]

[optional footer(s)]

2. 类型（必填）

提交消息的第一个词必须是类型，即描述变更类别的名词。使用小写。

类型	适用场景
feat	添加新功能（对应 SemVer 中的 MINOR）
fix	修复缺陷（对应 SemVer 中的 PATCH）
docs	仅修改文档
style	修改代码风格（格式、空白字符），不改变逻辑
refactor	重构代码，既不修复缺陷，也不添加功能
perf	提升性能
test	添加或更正测试
build	修改构建系统或外部依赖
ci	修改 CI 配置文件和脚本
chore	维护任务，不修改 src 或 test 文件
revert	撤销之前的提交

决策树：

• 是否添加了用户可感知的新功能？→ feat
• 是否修复了故障？→ fix
• 是否改变了代码结构，但没有改变行为？→ refactor
• 是否只影响测试？→ test
• 是否只影响文档？→ docs
• 是否提升了速度或资源使用效率？→ perf
• 是否修改了构建/CI 配置？→ build 或 ci
• 以上都不是？→ chore

3. 范围（可选）

可以在类型后面的括号中提供范围，以指明受影响的代码库部分。范围必须是名词。

feat(auth): add OAuth2 login flow
fix(parser): handle empty arrays correctly
docs(readme): update installation instructions

在项目中一致地使用范围。常见范围包括模块名称、功能区域或软件包名称。

4. 工单编号（推荐）

将问题跟踪系统中的工单编号作为提交范围。请从当前 git 分支名称中提取工单编号。

规则：

1. 运行 git branch --show-current 获取分支名称。
2. 提取工单编号，即符合 <PROJECT>-<number> 模式的大写标识符（例如 XODO-123、PROJ-42）。
3. 在类型后面的括号中使用工单编号作为范围。
4. 如果无法从分支名称中确定工单编号，则省略。

// Branch: feat/XODO-123-add-user-registration
feat(XODO-123): add user registration page

// Branch: fix/XODO-456-login-session-expired
fix(XODO-456): resolve login failure when session is expired

// Branch: main (no ticket number)
chore: update dependencies

5. 描述（必填）

描述紧跟在类型/范围前缀（以及工单编号，如有）的冒号和空格之后。

规则：

1. 使用祈使语气（使用“add feature”，而不是“added feature”或“adds feature”）。
2. 首字母不要大写。
3. 末尾不要加句号。
4. 保持简洁，建议总长度（类型 + 范围 + 描述）少于 72 个字符。
5. 描述提交做了什么，而不是如何做。

// Bad
feat: Added the new user registration page.
fix: This fixes the bug where users couldn't log in

// Good
feat: add user registration page
fix: resolve login failure when session is expired

6. 正文（可选）

可以在描述后空一行添加较长的正文。使用正文解释做了什么以及为什么，而不是如何做（差异内容会展示如何实现）。

• 自由格式文本。
• 可以包含多个段落，段落之间以空行分隔。
• 使用祈使语气。

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.

7. 页脚（可选）

页脚位于正文后空一行处。每个页脚由一个标记、一个分隔符（: 或 #）和一个值组成。

常见页脚：

• BREAKING CHANGE: <description> — 表示 API 存在不兼容变更（对应 SemVer 中的 MAJOR）
• Refs: #<issue-number> — 引用相关问题
• Reviewed-by: <name> — 标注审阅者
• Co-authored-by: <name> <email> — 标注共同作者

页脚标记中使用 - 替代空格（例如 Acked-by），但 BREAKING CHANGE 可以保持原样。

8. 破坏性变更

破坏性变更必须通过以下两种方式之一（或两者）标明：

1. 在类型／范围之后、冒号之前添加 !：

   feat!: remove deprecated API endpoints
   feat(api)!: change response format for /users
   

2. 添加 BREAKING CHANGE: 页脚：

   feat: change response format for /users
   
   BREAKING CHANGE: the /users endpoint now returns an array instead of an object wrapper
   

如果使用了 !，可以省略 BREAKING CHANGE: 页脚，并由描述说明破坏性变更。

9. 每次提交只包含一个逻辑变更

每次提交必须恰好代表一个逻辑变更。如果一次提交符合多个类型，应拆分成多次提交。

• 不要在同一次提交中混合错误修复和重构。
• 不要将某项功能与不相关的样式变更混在一起。
• 这样可以生成有意义的变更日志，并便于干净地撤销提交。

10. 示例

feat(XODO-123): add email notification on order completion

fix(XODO-456): resolve token refresh loop on expired sessions

docs(XODO-789): correct installation steps for Docker setup

refactor(XODO-101): extract price calculation into dedicated service

feat(XODO-202)!: change pagination response envelope

BREAKING CHANGE: list endpoints now return { data, meta } instead of a flat array

Refs: #452

revert(XODO-123): add email notification on order completion

Refs: 676104e

11. 验证清单

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

• 以有效的小写类型开头。
• 范围（如果有）是括号内的名词。
• 类型／范围与描述之间用冒号和空格分隔。
• 将分支中的工单号用作范围（如果有）。
• 描述使用祈使语气，首字母小写，末尾不加句号。
• 第一行总长度不超过 72 个字符。
• 正文（如果有）前有一个空行。
• 使用 ! 和／或 BREAKING CHANGE: 页脚标明破坏性变更。
• 此次提交只代表一个逻辑变更。

参考资料

• Conventional Commits 1.0.0