# 提交信息规范（Commit Messages）

提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。

## 1. 目标

- 让每次提交都能被独立理解。
- 支持快速定位问题与版本回滚。
- 可被工具解析（变更日志/发布流程）。

## 2. 格式

推荐使用以下结构（emoji 可选）：

```
:emoji: type(scope): subject

body

footer
```

- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。
- `type`：变更类型，必须从 4 的对应表中选取。
- `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。
- `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。
- `body`：可选，说明动机、关键实现、影响面；每行建议 ≤ 72 字符。
- `footer`：可选，关联任务/缺陷号，或 `BREAKING CHANGE:` 说明不兼容变更。

不使用 emoji 时，首行直接写 `type(scope): subject` 即可。

## 3. 约定

### 3.1 一次提交的边界

- 一个提交对应一个**逻辑变更**，而不是一个文件或一个模块。
- 可以同时修改多个 `unit/class/function`，只要它们属于同一逻辑变更。
- **允许合并的情况**：联动修改是变更所必需的同步/适配（不一起提会导致编译失败、测试失败或行为不一致）。
  - 例：改了 A 的接口签名，同时更新 B 的调用点。
- **应当拆分的情况**：改动彼此独立，仅是“顺手优化/无关重构/额外功能”。
  - 例：在修复 A 的 bug 时顺便重构 B 的内部实现。
- 实用判断：
  1. 这次提交能用一句话概括吗？若需要两句话，考虑拆分。
  2. 若只回滚其中一部分，系统还能保持正确吗？不能则不拆。
  3. 每个提交是否都能保持可运行/可构建/测试不更坏？做不到则合并。

### 3.2 大模块重构的提交拆分

当重构整个模块并影响到其他模块时，建议按“可回滚的小步”拆分提交：

1. **前置整理**：仅做无行为影响的清理（重命名、抽函数、补注释/类型、补测试）。
2. **核心重构**：在模块内部做结构调整，尽量保持对外接口不变；必要时加适配层。
3. **迁移调用方**：逐步把其他模块迁移到新接口/新行为上。
4. **清理旧接口**：确认无人使用后再删除适配层/旧代码。

若重构为破坏性变更，优先采用“两阶段”：先引入新接口并兼容旧接口（deprecated），迁移完成后再删除旧接口。

### 3.3 其他约定

- `subject` 尽量 ≤ 72 字符；必要时用 `body` 补充细节。
- `body/footer` 说明“为什么改、影响什么”，而不是复述代码。

## 4. 提交类型与 Emoji 对应

本仓库采用固定的 `type`/emoji 一一对应关系；使用 emoji 时必须使用对应的那一个，不得错配。

| type        | emoji（预览 / 代码）              | 说明                         |
| ----------- | --------------------------------- | ---------------------------- |
| `init`      | :tada: `:tada:`                   | 初始化/首次发布              |
| `feat`      | :sparkles: `:sparkles:`           | 新功能                       |
| `fix`       | :bug: `:bug:`                     | Bug 修复                     |
| `perf`      | :rocket: `:rocket:`               | 性能优化                     |
| `refactor`  | :recycle: `:recycle:`             | 重构（行为不变）             |
| `style`     | :art: `:art:`                     | 代码样式/格式（行为不变）    |
| `docs`      | :memo: `:memo:`                   | 文档更新                     |
| `test`      | :white_check_mark: `:white_check_mark:` | 测试新增/修正           |
| `deps`      | :package: `:package:`             | 依赖更新                     |
| `security`  | :lock: `:lock:`                   | 安全修复                     |
| `deprecate` | :warning: `:warning:`             | 废弃/弃用标记                |
| `remove`    | :wastebasket: `:wastebasket:`     | 删除功能/代码                |
| `chore`     | :wrench: `:wrench:`               | 构建/配置/工具/维护性改动    |
| `contrib`   | :busts_in_silhouette: `:busts_in_silhouette:` | 贡献者/致谢相关 |
| `release`   | :bookmark: `:bookmark:`           | 发布/打版本标签              |

注：`:white_check_mark:` 为补充图例，用于 `test` 类型。

如需新增新的 `type`，必须同时补充对应 emoji 与说明。

---

## 5. 版本号规范（SemVer）

遵循语义化版本规范。

### 5.1 格式

```txt
MAJOR.MINOR.PATCH
```

### 5.2 字段说明

| 字段      | 说明     | 何时递增           |
| --------- | -------- | ------------------ |
| **MAJOR** | 主版本号 | 不兼容的 API 修改  |
| **MINOR** | 次版本号 | 向后兼容的功能新增 |
| **PATCH** | 修订号   | 向后兼容的问题修正 |

### 5.3 更新规则

- **MAJOR（主版本）**：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。
- **MINOR（次版本）**：新增功能但保持兼容。递增后 PATCH 重置为 0。
- **PATCH（修订）**：仅修复 bug，不新增功能。

### 5.4 示例

```txt
1.0.0    # 首个稳定版
1.1.0    # 新增功能
1.1.1    # Bug 修复
2.0.0    # 破坏性变更
```

### 5.5 Pre-release 版本

```txt
1.0.0-alpha.1
1.0.0-beta
1.0.0-rc.1
1.0.0
```

### 5.6 初始开发阶段

```txt
0.1.0    # 初始版本
0.2.0    # API 未稳定
1.0.0    # 首个稳定版
```

注意：`0.x.x` 版本可以随时破坏兼容性。

---

## 6. 示例

带 emoji：

```
:sparkles: feat(order): add batch cancel api

support canceling multiple orders in one request; keep old api unchanged.

Refs: TSL-1234
```

不带 emoji：

```
refactor(order): simplify cancel flow
```