介绍
# Conventional Commits
根据 [约定式提交](https://www.conventionalcommits.org/en/v1.0.0/) 规范格式化所有提交信息。这使得能够自动生成更新日志、语义化版本控制以及拥有更好的提交历史。
## 格式结构
``` <type>[optional scope]: <description>
[optional body]
[optional footer(s)] ```
## 提交类型
### 必需类型
- **`feat:`** - 新功能（对应语义化版本控制中的 MINOR） - **`fix:`** - 缺陷修复（对应语义化版本控制中的 PATCH）
### 常见附加类型
- **`docs:`** - 仅文档变更 - **`style:`** - 代码风格变更（格式化、缺少分号等） - **`refactor:`** - 代码重构，不包含缺陷修复或新功能 - **`perf:`** - 性能改进 - **`test:`** - 添加或更新测试 - **`build:`** - 构建系统或外部依赖项变更 - **`ci:`** - CI/CD 配置变更 - **`chore:`** - 不修改 src 或 test 文件的其他变更 - **`revert:`** - 回滚先前的提交
## 作用域
可选的作用域提供关于代码库部分的额外上下文信息：
``` feat(parser): add ability to parse arrays fix(auth): resolve token expiration issue docs(readme): update installation instructions ```
## 描述
- 必须紧跟在类型/作用域后的冒号和空格之后 - 使用祈使语气（例如“add feature”，而不是“added feature”或“adds feature”） - 首字母不要大写 - 末尾不要加句号 - 保持简洁（通常为 50-72 个字符）
## 正文
- 可选的较长描述，提供额外上下文 - 必须在描述之后空一行开始 - 可以由多个段落组成 - 解释变更的“是什么”和“为什么”，而不是“怎么做”
## 破坏性变更
破坏性变更可以通过两种方式表示：
### 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`