git-workflow-and-versioning

Git 工作流和版本控制

技能概述

Git 工作流和版本控制提供了一套完整的版本管理最佳实践，帮助开发团队建立高效的代码协作流程，从提交规范到版本发布，覆盖代码管理的全生命周期。

适用场景

1. 日常代码开发与协作

当你需要进行任何代码更改时，这套工作流确保每个增量都被正确提交、审查和版本化。无论是单人项目还是大型团队协作，原子提交和描述性消息的实践让代码历史清晰可追溯，便于代码审查和问题排查。

2. 分支管理和并行开发

在处理多个功能特性、Bug 修复或发布管理时，基于主干开发的策略和短生命周期分支原则帮助团队避免合并冲突，保持主线始终可部署。使用 Git worktree 可以让多个 AI 代理或团队成员在不同分支上并行工作而不相互干扰。

3. 版本发布和变更管理

当项目有外部消费者时，语义化版本控制（Semantic Versioning）和标签管理为版本发布提供了清晰的契约。变更日志的维护让用户了解每个版本的影响，而规范的版本号升级策略确保消费者能够安全地评估和执行升级。

核心功能

1. 基于主干开发和分支管理

推荐采用基于主干开发（Trunk-Based Development）的策略，保持 main 分支始终处于可部署状态。特性分支应该短生命周期（1-3天内合并），避免长期分支带来的合并风险和集成延迟。对于需要在发布期间稳定代码同时主线继续开发的情况，可以创建发布分支，但应该尽快完成。相比长期分支，更推荐使用特性标志（Feature Flags）来管理未完成的功能。

2. 原子提交和描述性消息

每个成功的增量都应该有自己的提交，目标是每次提交约 100 行代码。原子提交原则要求每个提交只做一个逻辑上的事情，避免将格式更改、重构和新功能混合在一起。提交消息应该解释"为什么"而不仅仅是"什么"，使用标准的类型前缀（feat、fix、refactor、test、docs、chore），并在消息体中说明变更的意图和上下文。

3. 语义化版本控制

对于有外部消费者的项目，版本号应该遵循 MAJOR.MINOR.PATCH 的语义化规范：MAJOR 表示不兼容的 API 变更，MINOR 表示向后兼容的新功能，PATCH 表示向后兼容的 Bug 修复。版本号是一个承诺，必须确保代码变更与版本升级相匹配。发布时应该打上 Git 标签，让标签成为版本的真实来源，而不是在多个文件中手动维护版本号。

4. 变更摘要和审查支持

每次修改后提供结构化的变更摘要，包括"做了什么变更"、"故意没有碰什么"和"潜在问题"三个部分。这种模式让审查者清楚地了解变更的范围，发现错误假设，并展示对范围的把控。特别是"没有碰什么"部分，展示了变更的纪律性和避免未经授权的重构。

5. 提交前卫生检查

在每次提交前执行标准检查流程：查看暂存的更改、确保没有泄露密钥、运行测试、执行代码检查和类型检查。这些检查可以通过 git hooks（如 lint-staged + husky）自动化执行，防止不规范的代码进入仓库。同时，正确的 .gitignore 配置确保不会意外提交构建产物、环境文件或 IDE 配置。

常见问题

为什么推荐基于主干开发而不是长期特性分支？

基于主干开发强调保持主线始终可部署，特性分支在 1-3 天内完成并合并。长期分支是隐性成本——它们每天积累合并风险，导致集成延迟，而 DORA 研究持续表明基于主干开发与高效工程团队相关联。当需要同时进行发布稳定和主线开发时，可以使用发布分支，但应该尽快完成。相比在长期分支上保留未完成功能，更推荐使用特性标志来管理 incomplete 功能的部署。

如何判断一个变更应该是 MAJOR、MINOR 还是 PATCH 版本升级？

语义化版本控制的判断基于消费者能观察到的变化：PATCH 用于向后兼容的 Bug 修复，MINOR 用于向后兼容的新功能，MAJOR 用于任何不兼容的 API 变更。关键原则是"当不确定是否是破坏性变更时，假设它是"，因为意外的主版本升级比破坏消费者更廉价。需要注意的是，行为变更即使代码量很小，如果影响了消费者依赖的行为，也应该视为主版本升级。这与 Hyrum's Law 相关——当消费者依赖于实现细节时，看似"小"的变更也可能造成破坏。

提交信息应该包含哪些内容，什么样的格式才算规范？

规范的提交消息应该解释"为什么"而不仅仅是"什么"，使用格式 <type>: <short description> 后面可选的正文部分说明变更意图。类型包括 feat（新功能）、fix（Bug 修复）、refactor（重构）、test（测试）、docs（文档）、chore（工具配置）。消息体应该说明变更的原因和上下文，而不是显而易见的差异描述。例如，"feat: add email validation to registration endpoint" 加上说明"Prevents invalid email formats from reaching the database. Uses Zod schema validation..." 比简单的 "update auth.ts" 有用得多。另外，应该将格式更改与行为更改分离，将重构与新功能分离——每种类型的变更都应该是单独的提交。

团队如何制定适合自己的 Git 工作流规范？

团队制定 Git 工作流规范时，应该从项目的实际需求出发，而不是盲目套用现有框架。核心原则包括：原子提交、小而频繁的更改、描述性消息、明确的分支策略。如果团队已经在使用 Gitflow 或其他长期分支模型，可以调整这些原则来适应现有的分支模型——提交纪律比具体的分支策略更重要。关键是建立共识：提交消息要解释意图而非描述差异、保持分支短生命周期、在变更时而不是发布时编写变更日志、每次发布打标签并让标签成为版本的真实来源。对于 AI 代理参与的团队，额外的考虑点包括使用 worktree 支持并行开发、建立保存点模式确保每步都可回退、以及明确的变更摘要模板让 AI 代理输出结构化的审查信息。