6.0 KiB

Raw Permalink Blame History

提交信息规范（Commit Messages）

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

1. 目标

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

2. 格式

推荐使用以下结构（emoji 可选，但建议默认带上以便快速扫读）：

:emoji: type(scope): subject

body

footer

emoji：可选，位于首行行首；若使用，必须与 type 一一对应（见 4）。为保持一致性，建议默认使用 emoji；若不使用则省略即可。
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 大模块重构的提交拆分

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

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

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

3.3 其他约定

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

4. 提交类型与 Emoji 对应

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

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

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

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

5. 版本号规范（SemVer）

遵循语义化版本规范。

5.1 格式

MAJOR.MINOR.PATCH

5.2 字段说明

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

5.3 更新规则

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

5.4 示例

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

5.5 Pre-release 版本

1.0.0-alpha.1
1.0.0-beta
1.0.0-rc.1
1.0.0

5.6 初始开发阶段

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

6.0 KiB Raw Permalink Blame History Unescape Escape