Git Commit Message 规范：写出清晰、可维护的提交记录

文章目录

- [📌 常见示例汇总（快速查阅）](#📌 常见示例汇总（快速查阅）)
- - [🆕 新功能 (feat)](#🆕 新功能 (feat))
  - [🐞 修复 Bug (fix)](#🐞 修复 Bug (fix))
  - [📚 文档更新 (docs)](#📚 文档更新 (docs))
  - [⚙️ 重构 (refractor)](#⚙️ 重构 (refractor))
  - [🚀 性能优化 (perf)](#🚀 性能优化 (perf))
  - [🧪 测试 (test)](#🧪 测试 (test))
  - [🧹 杂项 (chore)](#🧹 杂项 (chore))
  - [💥 不兼容变更](#💥 不兼容变更)
- [一、为什么需要规范 Commit Message？](#一、为什么需要规范 Commit Message？)
- [二、Conventional Commits 规范详解](#二、Conventional Commits 规范详解)
- - [1. Header（必需）](#1. Header（必需）)
  - [2. Body 与 Footer（可选）](#2. Body 与 Footer（可选）)
- [三、Scope 怎么写？------尤其适用于深度学习项目](#三、Scope 怎么写？——尤其适用于深度学习项目)
- - [✅ 推荐 scope（算法/模型项目）](#✅ 推荐 scope（算法/模型项目）)
  - [📌 示例对比](#📌 示例对比)
- 四、最佳实践建议
- [五、如何使用 `.gitmessage` 模板（超简单！）](#五、如何使用 .gitmessage 模板（超简单！）)
- - [步骤 1：在项目根目录创建 `.gitmessage`](#步骤 1：在项目根目录创建 .gitmessage)
  - [步骤 2：启用模板（仅当前项目）](#步骤 2：启用模板（仅当前项目）)

📌 常见示例汇总（快速查阅）

🆕 新功能 (feat)

feat(model): add Vision Transformer backbone
feat(data): support COCO-style augmentation

🐞 修复 Bug (fix)

fix(loss): correct gradient flow in focal loss
fix(train): handle empty batch in DDP

📚 文档更新 (docs)

docs(config): document learning rate schedule

⚙️ 重构 (refractor)

refactor(data): migrate to torchvision transforms v2

🚀 性能优化 (perf)

perf(train): enable mixed-precision with autocast

🧪 测试 (test)

test(eval): add mAP calculation for detection

🧹 杂项 (chore)

chore(experiment): integrate Weights & Biases logging

💥 不兼容变更

text 复制代码

refactor(model): remove legacy ResNet-18 config

BREAKING CHANGE: Default backbone is now ViT-B/16.
Update your config.yaml accordingly.

Closes #42

一、为什么需要规范 Commit Message？

提升可读性：快速理解变更目的
支持自动化：语义化版本、CHANGELOG 自动生成
简化协作：审查者聚焦逻辑，而非猜测意图
便于追溯 ：通过 git log 快速定位问题模块

二、Conventional Commits 规范详解

格式：

复制代码

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type ：feat、fix、docs、refactor、perf、test、build、ci、chore 等
Scope（可选） ：按逻辑功能模块命名（见下文详解）
Description：祈使句、小写开头、无句号、≤72 字符

✅ 示例：
feat(model): add Swin Transformer
fix(data): skip corrupted samples in loader

2. Body 与 Footer（可选）

Body：解释"为什么改"，非"怎么改"
Footer ：关联 Issue（Closes #123）或标注破坏性变更（BREAKING CHANGE: ...）

三、Scope 怎么写？------尤其适用于深度学习项目

核心原则：按功能模块或流程阶段，而非文件路径。

✅ 推荐 scope（算法/模型项目）

Scope	说明
`model`	网络结构（如 ViT、ResNet）
`loss`	损失函数设计
`data`	数据加载、预处理、增强
`train`	训练流程、checkpoint
`eval`	评估指标、验证逻辑
`inference`	推理/部署
`config`	超参与配置
`utils`	工具函数（可视化、日志等）
`experiment`	实验跟踪（W&B、TensorBoard）

📌 示例对比

不推荐 ❌	推荐 ✅
`feat(src/models/vit.py): ...`	`feat(model): add ViT-B/16 support`
`fix(train_loop.py): ...`	`fix(train): handle NaN loss gracefully`
`refactor(utils/vis.py): ...`	`refactor(utils): improve attention map visualization`

💡 自测问题 ：如果在组会上汇报，你会说"我改了什么部分"？

------ 那就是你的 scope！

四、最佳实践建议

一次提交只做一件事 → 保持原子性
避免模糊描述 ：❌ update model ✅ feat(model): add dropout to classifier head
优先使用英文 → 便于工具解析与协作
团队统一 scope 词典 → 在 CONTRIBUTING.md 中定义常用 scope

五、如何使用 `.gitmessage` 模板（超简单！）

步骤 1：在项目根目录创建 `.gitmessage`