git-workflow

Git 工作流

有效的版本控制不仅仅是跟踪变更，更是让团队能够可预测地协作、充满信心地发布，并维护一段脉络清晰的历史记录。合适的工作流取决于团队规模、发布节奏，以及项目在不减慢进度的前提下能够承受多少流程。

选择分支策略

没有一种分支模型适用于所有团队。正确的选择取决于发布频率、团队规模，以及团队能够接受多少流程。

策略比较

策略	发布节奏	团队规模	复杂度	适用场景
主干开发	持续（每天多次）	任意（配合强大的 CI 效果最佳）	低	SaaS、云原生项目、CI/CD 成熟的团队
GitHub Flow	按需（每次合并 PR 时）	小型到中型	低	Web 应用、初创公司、希望保持简单的团队
Git Flow	按计划／按版本发布	中型到大型	高	打包软件、移动应用、支持多个版本的项目
GitLab Flow	按环境推进	中型到大型	中	需要环境专属分支（staging、production）的团队

决策指南

1. 是否持续部署？ - 使用主干开发。前提是使用短期分支（数小时，而不是数天）、为未完成的工作启用功能标志，并具备强大的 CI。
2. 是否在合并时部署，但需要审核关卡？ - 使用 GitHub Flow。采用一个长期分支（main）、功能分支，并以拉取请求作为合并关卡。
3. 是否按计划发布带版本号的版本？ - 使用 Git Flow。分设 develop 和 main 分支，用发布分支进行稳定化，并用热修复分支处理紧急补丁。
4. 是否需要在不同环境间推进？ - 使用 GitLab Flow。环境分支（staging、production）位于 main 的下游，合并沿单一方向进行。

有关详细的操作机制、功能标志集成以及策略迁移路径，请参阅 分支策略参考。

---

提交消息约定

优秀的提交消息面向三类读者：审阅 PR 的审核者、下个月查看 git log 的开发者，以及生成变更日志和版本更新的自动化工具。

Conventional Commits 格式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

常见提交类型

类型	用途	版本影响
feat	对用户可见的新功能	次版本更新
fix	错误修复	补丁版本更新
refactor	重构代码，但不改变行为	无
perf	性能改进	补丁版本更新
test	添加或更新测试	无
docs	仅文档变更	无
chore	工具、依赖项、构建配置	无
ci	CI/CD 流水线变更	无
build	构建系统或依赖项变更	无

破坏性变更

在类型后追加 !，或添加 BREAKING CHANGE: 页脚，以标示不兼容变更。使用自动化发布工具时，任一标记都会触发主版本更新。

feat(api)!: remove deprecated /v1/users endpoint

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

与语义化版本对齐

提交包含	版本更新	示例
fix:	补丁版本（1.0.0 -> 1.0.1）	错误修正
feat:	次版本（1.0.0 -> 1.1.0）	新功能
BREAKING CHANGE 或 !	主版本（1.0.0 -> 2.0.0）	不兼容变更

有关作用域命名模式、多行正文指南、变更日志自动化设置以及 git 钩子验证，请参阅 提交约定参考。

---

拉取请求工作流

在大多数 git 工作流中，拉取请求是协作的主要环节。其质量会直接影响审阅速度、缺陷发现和团队效率。

PR 大小指南

PR 大小（变更行数）	评审质量	建议
< 50	优秀——评审者能发现大多数问题	适合堆叠式 PR
50-200	良好——认知负担适中	适合大多数变更的理想范围
200-400	尚可——需要集中时间评审	单次评审的上限
400+	较差——评审者容易疲劳，缺陷容易漏过	拆分为更小的 PR

PR 核心实践

• 每个 PR 只处理一个关注点——一个 PR 应只做一件事：添加功能、修复错误或重构模块。混合多个关注点会增加评审难度，也会提高回滚风险。
• 写清楚描述——说明变更内容、变更原因以及验证方法。链接到相关工单或问题。
• 保持差异易于评审——将大型机械性变更（重命名、格式调整）与逻辑变更拆分到不同的 PR 中。
• 及时响应反馈——过时的 PR 会累积合并冲突，并阻碍依赖它的工作。

合并策略

策略	历史记录形态	适用场景
合并提交	保留分支拓扑，创建合并节点	开源项目、审计追踪
压缩并合并	将分支折叠为 main 上的单个提交	中间提交杂乱的功能分支
变基并合并	线性历史记录，不包含合并提交	希望获得整洁线性日志的团队

请参阅 PR 模式参考，了解描述模板、CODEOWNERS 配置、分支保护规则、堆叠式 PR 工作流和评审分配策略。

---

发布管理

发布管理连接开发与部署。具体方式取决于发布是持续进行、按计划进行，还是按版本进行。

发布模式

模式	运作方式	适用场景
持续发布	每个合并的 PR 都会自动部署	CI/CD 和监控完善的 SaaS
定期发布	累积变更，并按固定周期发布（每周、每两周）	需要协调窗口的团队
版本化发布	使用明确的版本标签，并通过发布分支进行稳定化	库、API、打包软件

用于发布的 Git 标签

标签将特定提交标记为发布节点。发布时请使用附注标签，因为它们会存储作者、日期和消息元数据。

# Create an annotated release tag
git tag -a v1.2.0 -m "Release 1.2.0: Add user dashboard and fix auth timeout"

# Push tags to remote
git push origin v1.2.0

# List existing tags matching a pattern
git tag -l "v1.*"

自动化发布流水线

将约定式提交与发布自动化工具结合后，流水线可以：

1. 分析上一个标签以来的提交，以确定下一个版本
2. 根据提交消息生成或更新变更日志
3. 创建 git 标签
4. 构建并发布制品
5. 在托管平台（GitHub/GitLab）上创建发布条目

这样可以省去手动确定版本的工作，并确保变更日志与实际变更保持同步。

热修复工作流

在生产环境中发现严重错误时：

1. 从发布标签创建分支（而不是从开发分支创建）
2. 应用最小化修复
3. 为新的补丁版本打标签
4. 将修复向前合并到主开发线，以防止回归

# Branch from the release tag
git checkout -b hotfix/fix-auth-crash v1.2.0

# After fixing and committing
git tag -a v1.2.1 -m "Hotfix: prevent auth crash on expired tokens"
git push origin v1.2.1

# Merge fix back to main
git checkout main
git merge hotfix/fix-auth-crash

---

快速参考：常见工作流问题

问题	可能原因	解决方案
经常发生合并冲突	分支生命周期长、集成不频繁	每天将 main 合并到功能分支，或改用主干开发
main 分支损坏	PR 未运行 CI、测试覆盖不足	要求合并前 CI 通过，并添加分支保护
发布内容不明确	没有提交约定、变更日志靠手动维护	采用约定式提交，自动生成变更日志
PR 评审缓慢	PR 过大、所有权不明确	制定大小指南、配置 CODEOWNERS、使用堆叠式 PR
意外提交到 main	没有分支保护	启用分支保护规则，并要求 PR 评审

---

参考文件

参考	内容
分支策略	Trunk-based、GitHub Flow、Git Flow、GitLab Flow——机制、功能标志、对比矩阵
提交约定	Conventional commits 格式、范围模式、语义化版本、变更日志自动化、git 钩子
PR 模式	大小指南、描述模板、CODEOWNERS、合并策略、分支保护、堆叠式 PR

---

与其他技能集成

情况	推荐技能
设置用于分支保护的 CI/CD 流水线	从 krzysztofsurdy/code-virtuoso 安装 knowledge-virtuoso，以获取测试策略
将 API 版本控制与 git 发布标签对齐	从 krzysztofsurdy/code-virtuoso 安装 knowledge-virtuoso，以获取 API 设计原则
协调跨微服务的发布	从 krzysztofsurdy/code-virtuoso 安装 knowledge-virtuoso，以获取微服务模式
与 Sprint 对齐的发布规划	从 krzysztofsurdy/code-virtuoso 安装 knowledge-virtuoso，以获取 scrum 工作流