Git 提交与 Code Review 规范指南

提交内容规范

比提交信息更重要的是提交的内容本身。核心原则是原子提交。

• 一个提交只做一件事：正确示例是提交 A 只实现新功能，提交 B 只重构相关代码，提交 C 只修改文档。错误示例是一个提交里既修复了 bug，又重构了代码，还顺手格式化了文件。
• 为什么原子提交重要？ 易于审查，审查者可以轻松理解一个小的、逻辑完整的变更。易于回滚，如果某个功能引入问题，可以安全地回滚单个提交。易于定位问题，使用 git bisect 等工具时，原子提交能快速定位引入问题的具体变更。

与 Code Review 流程的结合

提交规范是 Code Review 的前置条件。一个理想的流程如下：

场景：为购物车添加商品数量验证功能

首先创建功能分支：

git checkout -b feature/add-cart-quantity-validation

接下来进行原子开发与提交。

提交 1：添加验证逻辑

# 假设你修改了 shopping_cart.py
git add shopping_cart.py
git commit -m "feat(cart): add quantity validation for items

Validate that item quantity is a positive integer.
Throw `InvalidQuantityError` if validation fails.
Add relevant unit tests for valid and invalid cases."

提交 2：更新 API 文档

# 假设你更新了 api_docs.md
git add api_docs.md
git commit -m "docs(api): update cart endpoint docs with quantity rules

Document the new validation rule for the `quantity` field in the `POST /cart/items` endpoint."

推送到远程并发起 Pull Request (PR) / Merge Request (MR)。此时，你的 PR 中将包含两个清晰、独立的提交。审查者可以快速浏览提交历史，了解工作内容，分别审查每个提交。如果发现文档有问题，可以直接评论在第二个提交上，而不会影响第一个提交的讨论。

根据审查意见修改时，不要直接提交新的补丁，而是使用 git commit --amend 或 git rebase -i 来修正上一个相关的提交，保持历史整洁。

# 修改 shopping_cart.py 文件，添加上限检查
git add shopping_cart.py
git commit --amend
# 在打开的编辑器中，更新提交信息（如果需要的话）：
# feat(cart): add quantity validation for items
#
# - Validate that item quantity is a positive integer between 1-99.
# - Throw `InvalidQuantityError` if validation fails.
# - Add relevant unit tests for valid and invalid cases.

由于修改了历史，需要强制推送（在功能分支上通常是安全的）：

git push -f origin feature/add-cart-quantity-validation

PR/MR 会自动更新，审查者看到的是整理后最清晰的提交历史。

总结：优秀提交规范的核心价值

工具推荐：

• commitizen：一个交互式工具，帮助你生成符合规范（如 Angular Convention）的提交信息。
• husky + commitlint：在 Git 提交时自动检查提交信息格式，确保规范被遵守。

遵循良好的提交规范，不仅是对审查者的尊重，更是对项目未来可维护性的投资，也是每一位专业工程师应具备的基本素养。