第 4 章 Commit 规范

一次提交只做一件事，删除本次提交后项目仍可编译。

4.1 格式

<type>(<scope>): <subject>
<空行>
<body 四段，仅复杂提交需要>
<空行>
<footer: Closes # / Refs #>

4.2 type（固定，不可自造）

type	含义	场景
`feat`	新功能	新模块、新算法、新接口
`fix`	Bug 修复	代码错误、逻辑缺陷
`refactor`	重构	不改变功能的结构调整
`perf`	性能优化	提效、降内存
`docs`	文档	文档 / 注释 / README
`test`	测试	增改测试代码
`style`	代码风格	格式化、缩进（不影响功能）
`build`	构建系统	CMake、依赖、构建脚本
`ci`	持续集成	CI 配置、检查脚本
`chore`	杂项	日常维护
`revert`	回滚	撤销之前的提交

不要用 update / modify / fix（小写作 type 之外的随意写法）。

4.3 scope（实际模块名，小写英文）

参考样例可用：members / ci / docs / repo。正式项目的 scope 列表由维护者在 README 维护。

4.4 subject（必填）

动词开头，祈使句（"添加""修复"），不超过 50 字符。
描述"做了什么"。禁止 update / 修改 / test / 123 / fix something。

4.5 简单 vs 复杂

简单提交（补字段、改注释、修 typo）只写 subject：

feat(members): 添加张三的成员卡片

复杂提交（算法 / 逻辑 / 参数变更）写 body 四段：

feat(filter): 实现自适应卡尔曼滤波

背景：标准卡尔曼在观测异常时易发散，PPP 结果出现跳变。
修改：新增 adaptive_kalman 模块，实现基于残差的新息自适应。
验证：使用 WHU20250101，固定率 85.6% → 91.2%，无精度退化。
影响：默认不启用，需配置 filter_type=adaptive。

Closes #12

完整模板见 templates/commit-body.md。

Closes #12：完全解决该 Issue（PR 合并后自动关闭）。
Refs #34：部分相关或不关闭。
每个关联 Issue 单独一行。

4.7 提交前自检

检查项	通过标准
原子性	只做一件事
可回滚	删除后项目仍可编译
可复现	复杂提交 body 含背景/修改/验证/影响
type / scope / subject	符合上表，≤50 字，动词开头

4.8 参考样例

写一个简单提交和一个复杂提交。

简单提交（只写 subject）：

git checkout -b docs/tweak-readme
# 编辑 README.md 加一句话
git add README.md
git commit -m "docs(repo): 补充说明"

复杂提交（带 body 四段）。运行不带 -m 的 git commit，在编辑器里按结构写：

git commit

内容示例：

feat(ci): 增强 check-members 的邮箱校验

背景：此前只检查字段是否存在，邮箱格式错误无法发现。
修改：新增邮箱正则校验，非法邮箱直接报错。
验证：本地对 3 张卡片运行 check-members.py，非法邮箱被拦截。
影响：仅影响校验脚本，不改成员卡片格式。

Refs #2

vim 中按 i 编辑，Esc 后 :wq 保存。

自检：

python scripts/check-quest.py 4