Git 提交规范与更新日志生成指南

1. 目的

本规范用于统一团队 Git 提交信息格式，提升提交历史的可读性，并支持自动化生成更新日志（Changelog）。当前规则重点从提交记录中提取 feat 与 fix 两种类型作为对外发布版本的变更说明，其它类型用于内部开发管理。

2. 提交信息总体格式

2.1 标准格式

<type>(<scope>): <subject>

2.2 字段说明

字段 是否必填 说明
type 是 提交类型，用于分类和生成日志
scope 否（强烈建议） 影响的模块、子系统或功能域
subject 是 简要说明本次提交的目的和内容

2.3 示例

feat(render): 支持多视口渲染
fix(io): 修复大文件读取时的崩溃问题
chore(ci): 调整流水线缓存策略

3. type 取值规范（核心）

3.1 用于生成更新日志的类型（必须规范使用）

以下两种类型会被自动提取到更新日志中，属于对外可感知变更：

1️⃣ feat —— 新功能

  • 表示新增或扩展用户可感知的功能
  • 会出现在 Changelog 的 新增（Features） 部分

适用场景：

  • 新增模块 / 新接口 / 新命令
  • 功能性增强（非 Bug 修复）

示例：

feat(export): 新增 STL 批量导出功能

2️⃣ fix —— Bug 修复

  • 表示修复已存在的问题
  • 会出现在 Changelog 的 修复（Bug Fixes） 部分

适用场景：

  • 崩溃、逻辑错误、异常行为
  • 性能或稳定性问题修复

示例：

fix(memory): 修复对象析构顺序导致的内存泄漏

3.2 不进入更新日志的类型（内部管理）

以下类型不会被提取到更新日志，主要用于研发过程管理：

type 含义 示例
chore 构建、脚本、依赖调整 chore(cmake): 调整编译选项
refactor 代码重构（无功能变化） refactor(core): 重构事件系统
docs 文档变更 docs(readme): 更新编译说明
test 测试相关 test(io): 增加异常路径测试
style 格式、空格、命名调整 style(ui): 统一命名规范
perf 性能优化（无行为变化） perf(mesh): 优化简化算法性能
build 构建系统变更 build(vcpkg): 升级依赖版本
ci CI/CD 相关 ci(github): 增加自动发布任务

⚠️ 注意：

  • 即使是重要改动，只要不影响用户行为，也不要使用 feat 或 fix

4. scope（模块）规范

4.1 作用

  • 帮助快速定位变更影响范围
  • 提升日志可读性
  • 支持按模块过滤提交

4.2 推荐写法

  • 使用小写英文
  • 使用稳定、统一的模块名

示例：

arch / coord / gms / dfc / mep / common / inter /  ...

4.3 示例

feat(column): 柱子新增柱点绘制
fix(plot): 出图新增自动排图功能

5. subject（说明）书写规范

5.1 基本原则

  • 使用陈述句，描述“做了什么”
  • 简洁明确，避免实现细节
  • 不要以标点符号结尾

5.2 推荐 vs 不推荐

✅ 推荐：

fix(plot): 修复出图标高标注标注获取错误的问题

❌ 不推荐：

fix(io): fix bug
fix: 修改了一下

✅ 推荐：

fix(plot): 修复由于hz_type为空导致图纸无法保存的问题

- 为 hz_type 添加默认值 '排房图' 以防止空值问题
- 确保页面信息处理逻辑的完整性
- 保持文档信息缓存状态的一致性

❌ 不推荐：

fix(plot): 修复hz_type字段空值bug

6. 更新日志（Changelog）生成规则

6.1 提取规则

  • 仅提取 feat 和 fix
  • 按版本范围（tag / commit 区间）生成
  • 按类型分组输出

6.2 示例生成结果

## v2.3.0

### ✨ Features
- feat(dfc): DFC启动器新增自动更新关闭功能
- feat(arch): 墙体新增柱点绘制功能

### 🐛 Bug Fixes
- fix(dfc): 修复DFC启动容易崩溃的问题
- fix(plot): 修复出图标高标注标注获取错误的问题

7. 提交粒度要求

  • 一个提交 只做一件事
  • 不要混合 feat 和 fix
  • 重构与功能变更必须拆分提交

示例（正确）：

refactor(DFC): 重构路径偏移算法
feat(DFC): DFC启动器新增自动更新关闭功能

8. 团队执行要求

  1. 所有提交 必须符合格式
  2. feat / fix 使用错误将被要求重写提交（rebase）暂不启用
  3. 发布版本日志 仅以自动生成结果为准

9. 常见问题

Q：优化性能算不算 feat？
A：如果用户行为或能力发生变化 → feat，否则用 perf

Q：修复测试代码 Bug 用什么？
A：test，不要用 fix

Q：紧急修复线上问题？
A：仍然使用 fix，不要使用自定义类型

10. 总结（一句话规则）

用户能感知的新能力用 feat，用户能感知的问题修复用 fix，其它一律不用进入更新日志。

协作