约定式提交（Conventional Commits）

所有提交信息均须遵循 Conventional Commits 规范。此举支持自动生成变更日志（changelog）、实现语义化版本控制（Semantic Versioning），并提升提交历史的可读性与可维护性。

格式结构

<类型>[可选作用域]: <描述>

[可选正文]

[可选页脚（一个或多个）]

提交类型

必需类型

• feat: — 新增功能（对应语义化版本中的 MINOR 版本升级）
• fix: — 修复缺陷（对应语义化版本中的 PATCH 版本升级）

常用附加类型

• docs: — 仅文档变更
• style: — 代码风格变更（如格式调整、缺失分号等）
• refactor: — 既不修复缺陷也不新增功能的代码重构
• perf: — 性能优化
• test: — 增加或更新测试
• build: — 构建系统或外部依赖项变更
• ci: — CI/CD 配置变更
• chore: — 其他未修改 src 或 test 文件的变更
• revert: — 回退前一次提交

作用域（Scope）

作用域为可选项，用于提供关于代码库某一部分的额外上下文信息：

feat(parser): add ability to parse arrays
fix(auth): resolve token expiration issue
docs(readme): update installation instructions

描述（Description）

• 必须紧随类型/作用域后的冒号与空格之后出现
• 使用祈使语气（例如 “add feature”，而非 “added feature” 或 “adds feature”）
• 首字母不得大写
• 末尾不得加句号
• 保持简洁（通常建议长度为 50–72 个字符）

正文（Body）

• 为可选的较长说明，用于补充更多上下文
• 必须在描述后空一行开始
• 可由多个段落组成
• 应阐明变更的“是什么”（what）和“为什么”（why），而非“如何实现”（how）

不兼容变更（Breaking Changes）

不兼容变更可通过以下两种方式之一（或两者同时）标明：

1. 在类型/作用域中使用 !

feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped

2. 使用 BREAKING CHANGE 页脚

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

3. 同时使用两种方式

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

示例

简单功能提交

feat: add user authentication

带作用域的功能提交

feat(auth): add OAuth2 support

含正文的缺陷修复

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.

不兼容变更

feat!: migrate to new API client

BREAKING CHANGE: The API client interface has changed. All methods now
return Promises instead of using callbacks.

文档更新

docs: correct spelling of CHANGELOG

多段落正文 + 页脚

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.

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 提交
• 自动生成提交信息
• Pull Request 的合并提交
• 当用户询问有关提交信息或 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