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

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

🆕 新功能 (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

💥 不兼容变更

refactor(model): remove legacy ResNet-18 configBREAKING 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)]

1. Header（必需）

• 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！

---

四、最佳实践建议

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

---

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

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

# <type>(<scope>): <description>
#
# Example (DL project):
# feat(model): add Swin Transformer
# fix(data): skip corrupted images in loader
#
# Common scopes: model, loss, data, train, eval, config, utils, experiment
# Types: feat, fix, docs, refactor, perf, test, chore, build, ci
#
# Body: Explain *why*, not *how*. Keep lines < 72 chars.
# Footer: Closes #123 or BREAKING CHANGE: ...
#
# —— 删除注释后填写内容 ——

步骤 2：启用模板（仅当前项目）

git config commit.template .gitmessage

✅ 之后每次 git commit 都会自动加载模板，引导你写出规范提交。