git-workflow-and-versioning

Git 工作流和版本管理

概览

Git 是你的安全网。把 commits 当作保存点，把 branches 当作沙盒，把 history 当作文档。AI agents 会高速生成代码，而有纪律的版本控制是让变更可管理、可审查、可回滚的机制。

何时使用

始终使用。每个代码变更都经过 git。

核心原则

Trunk-Based Development（推荐）

保持 main 始终可部署。在短生命周期 feature branches 中工作，并在 1-3 天内合回。长期存在的开发分支是隐藏成本：它们会分叉、制造 merge conflicts，并延迟集成。DORA 研究持续表明，trunk-based development 与高绩效工程团队相关。

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

这是推荐默认方式。使用 gitflow 或长期分支的团队，可以把这些原则（atomic commits、小变更、描述性消息）适配到自己的分支模型中。commit 纪律比具体分支策略更重要。

• Dev branches 是成本。 分支每多存活一天，就会累积 merge 风险。
• Release branches 可以接受。 当你需要在 main 继续前进的同时稳定某个 release。
• Feature flags > long branches。 优先把未完成工作藏在 flags 后部署，而不是让它在分支上停留数周。

1. 尽早提交，经常提交

每个成功的增量都应该有自己的 commit。不要累积大量未提交变更。

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

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

Commits 是保存点。如果下一个变更破坏了东西，你可以立刻回到最后一个已知良好状态。

2. Atomic Commits（原子提交）

每个 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 messages 解释 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>

类型：

• feat — 新功能
• fix — Bug fix
• refactor — 既不修 bug 也不加功能的代码变更
• test — 添加或更新测试
• docs — 仅文档
• chore — 工具、依赖、配置