git-workflow-and-versioning

Git 工作流与版本管理

概览

Git 是你的安全网。把 commit 当作存档点，把 branch 当作沙箱，把历史当作文档。面对高速生成代码的 AI agent，严格的版本控制纪律，是让改动保持可管理、可评审、可回滚的关键机制。

何时使用

始终如此。每一项代码改动都应该经过 git。

核心原则

基于主干的开发（Trunk-Based Development，推荐）

让 main 始终保持可部署。使用 1-3 天内就回合并的短命 feature branch。长期存在的开发分支是一种隐性成本，它们会逐渐分叉、制造冲突，并推迟集成。DORA 的研究长期显示，trunk-based development 与高绩效工程团队显著相关。

main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches (1-3 days)

这是默认推荐做法。使用 gitflow 或长期分支的团队，也可以把这些原则迁移过去，例如原子提交、小改动、清晰描述。真正重要的是提交纪律，而不是某个固定分支模型。

• 开发分支本身就是成本。 分支每多活一天，就多积累一天合并风险
• 发布分支可以接受。 当你需要稳定某个版本，而 main 继续前进时
• Feature flags 优于长期分支。 相比在分支上挂几周，不如把未完成功能放在 flag 后面提前部署

1. 早点提交，经常提交

每个成功的增量都应该有独立 commit，不要堆出一大坨未提交改动。

Work pattern:
  Implement slice → Test → Verify → Commit → Next slice

Not this:
  Implement everything → Hope it works → Giant commit

Commit 就是存档点。下一个改动如果把东西弄坏了，你能立刻回到最后一个已知正确状态。

2. 原子提交

每个 commit 只做一件逻辑上的事：

# Good: Each commit is self-contained
git log --oneline
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state
m1n2o3p Add task creation tests (unit + integration)

# Bad: Everything mixed together
git log --oneline
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils

3. 描述性提交信息

Commit message 要解释 why，而不只是 what：

# Good: Explains intent
feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level,
consistent with existing validation patterns in auth.ts.

# Bad: Describes what's obvious from the diff
update auth.ts

格式：

<type>: <short description>

<optional body explaining why, not what>

常见 type：

• feat：新功能
• fix：bug 修复
• refactor：既不修 bug 也不加功能的代码改动
• test：补测或改测
• docs：纯文档改动
• chore：工具、依赖、配置

4. 把关注点分开

不要把格式化改动和行为改动混在一起，也不要把重构和功能混在一起。每一种类型的改动都应该是单独 commit，理想情况下也是单独 PR：