162 lines
5.8 KiB
Markdown
162 lines
5.8 KiB
Markdown
# 提交信息规范（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
|
||
```
|