Git开发分支管理规范

背景

基于过去数个月的GIT代码管理方面的磨合，为了更好适应我们现在开发测试上线的节奏和效率，减少同模式下多人开发提测的冲突等场景，保证整个不同环境和CICD的可靠性，提升协同效率，经过各个接口人的激烈讨论明确，我们规范从1.0升级到了1.1。

该Git分支管理规范专门设计用于多人协作、需要测试验收控制上线节奏的项目。通过建立完善的分支结构和合并规则，确保代码质量和发布安全性。

规范采用多分支并行开发模式，将开发、测试、发布流程有机分离。开发人员在feature分支进行功能开发，通过base分支进行集成测试，经过test环境验收后，通过release分支控制上线节奏，最终合并到main生产分支。这种设计有效避免了代码冲突，提高了发布质量，适合对代码稳定性和发布流程有严格要求的团队项目。

Git 分支管理规范

适用于多人协作、需要测试验收控制上线节奏的项目。

---

🎯 分支结构概览

graph TD MAIN[main] --准备发布分支--> REL(release/x.y.z<br>非必需) MAIN --功能开发分支--> F1(feature/xxx) MAIN --bug修复分支--> F2(bugfix/xxx) MAIN(main<br>（稳定主干分支）) --准备基准分支--> BASE-DEV(base-dev-vx.y<br>非必需) MAIN(main<br>（稳定主干分支）) --准备基准分支--> BASE-Test(base-test-vx.y<br>非必需) subgraph 功能开发 F1 --完成开发--> BASE-DEV F1 --dev完成测试--> BASE-Test F2 --完成修复--> BASE-DEV F2 --dev完成测试--> BASE-Test BASE-Test --部署测试环境--> TEST[test] BASE-DEV --部署开发环境--> DEV[dev] end subgraph 上线准备 F1 --验收通过(cr)--> REL F2 --验收通过(cr)--> REL end F2 --紧急修复(cr)--> MAIN REL --正常上线--> MAIN MAIN --tag发布--> TAG(vx.y.z) subgraph 上线发布 TAG(vx.y.z) end MAIN -.-> TEST MAIN -.-> DEV

---

📁 分支说明

分支名	用途说明
feature/*	新功能分支，从 main 创建，完成后合并到 base-xxx(测试联调)，或release(集中发布)
bugfix/*	Bug 修复分支，从 main 创建，修复完成后合并到 base-xxx(测试联调)，或release(集中发布)，或 main(紧急修复)
base-vx.y	所有功能和修复的集成主干，不直接上线，对应某个具体版本的开发
dev	用于部署dev环境，从 base-vx.y 合并而来，当出现不可解决冲突时，删除后从main重新checkout
test	用于部署test环境，从 base-vx.y 合并而来，当出现不可解决冲突时，删除后从main重新checkout
release/x.y	准备上线的功能集合，只合入已验收通过的功能
main	生产分支，正式发布版本来源分支，只从 release/x.y 合并

---

🔄 合并规则

来源分支	目标分支	合并条件 / 说明
feature/*	dev	完成功能开发、代码 review 后合并
bugfix/*	dev	修复完成、验证通过后合并
base-vx.y	test	每日/阶段性合并，部署测试环境
base-vx.y	dev	每日/阶段性合并，部署dev环境
feature/*	release/x.y	仅合并已验收通过的功能
bugfix/*	release/x.y	仅合并已验收通过的bug
release/x.y	main	上线发布前的最终确认步骤，合并后打 tag
main	dev	冲突无法解决时，从主干同步
main	test	冲突无法解决时，从主干同步

---

🚦 工作流程

1. 日常开发

git checkout main
git checkout -b feature/code-review
# 开发并提交代码
git push origin feature/code-review
# 提交 MR/PR → base-vx.y

2. 测试验收

git checkout test
git merge base-vx.y
# 触发 CI/CD 自动部署 test 环境

3. 准备上线（只上线已验收功能）

git checkout -b release/1.5.0 develop
# 从 feature 分支 merge 到 release/x.y

# 验证通过后上线：
git checkout main
git merge release/1.5.0
git tag v1.5.0

git checkout develop
git merge release/1.5.0

---

✅ 规则约定

• 禁止直接向 dev、test、main 、release/xxx分支直接 push

• 所有合并必须通过 Pull Request / Merge Request

• 所有上线功能必须在 test 环境验收通过后，才允许合入 main 或者release

• 每次上线必须打 Tag，并记录发布日志

• 如果通过release管理发布，bugfix分支修复完分两种情况（以下两种形式二选一）

  • 紧急上线：直接合并到main分支，并打tag上线，上线后通知相关方merge一次main分支新上线代码

  • 统一上线：先合并到release分支，通过release合并到main，切记不可以同时合并到 main 和 release

---

📌 示例版本流程

graph LR B[feature/payment] --开发完成--> BE C[bugfix/login-crash] --修复完成--> BE BE --更新dev--> D[dev] BE --更新test--> T[test] B --测试通过--> R[release/1.5.0] C --测试通过--> R[release/1.5.0] R --正常上线--> M[main] F[bugfix/payment-crash] --紧急修复--> M[main] M -.-> D M -.-> T M --上线发版--> TAG

---

如需配合 CI/CD，可根据 release/* 合并事件触发构建和上线部署。

Test环境部署注意事项：

1. 每个feature分支都基于一个独立的需求，由RD Owner统一拉分支，不允许不同需求在同一个feature分支上开发。

2. 多人同时开发一个需求（feature分支），分别拉取对应分支到本地，开发完再合并回feature分支上，合并过程中如有代码冲突由RD Owner处理确认。

3. 基于feature/bugfix分支开发过程中，如main分支有新上线，请及时合并代码到当前分支，及时解决代码冲突，再部署到test环境

4. 只有在Test环境测试通过的feature/bugfix分支，才可合并到release/main分支上线，不允许丢代码或者夹带私货上线。

生产环境部署注意事项

1. 基于 feature - main 上线流程的

   1. 必须每个 feature 验证完成后才允许上线后续 feature，禁止在未验证完成的情况下上线多个 feature

   2. 上线过程中出现 bug 时，需要立刻回滚止损，包括 bug 分支及其之后上线的全部分支

2. 基于 release - main 上线流程的

   1. 分支名称应符合如下命名规范：release/vx.y-mmdd-z，其中 z 对应当天第 z 次上线，如：release/v1.0-0826-3

   2. 必须预留至少 1 小时给 QA 进行线上验收

   3. 上线过程中出现 bug 时，需要立刻回滚止损该 release 提交，再次上线需修复该 bug，或摘除该 bug 涉及的提交