keyfil/文档/基础组件/20250627-Git分支管理规范（修订版）.md

20250627-Git分支管理规范（修订版）

分支策略概述

• 本规范基于 GitFlow 工作流，结合公司一些实际情况。规范明确了分支类型、使用场景、操作流程及权限控制。
• 支持多团队，多迭代并行开发
  • 多迭代通过 develop/xxx 区分
  • 多团队通过 feature/xxx 区分

分支类型与用途

1. 主分支 (master)

• 作用：生产环境代码，存放稳定可发布的版本
• 保护规则：
  • 禁止直接 push
  • 只接受来自 release 或 hotfix 分支的 Merge Request
  • 至少需要 2 个代码审查批准才能合并
  • 每次合并自动触发版本标签（X.Y.Z）

2. 项目迭代分支 (develop/xxx)

• 命名规范：develop/<date>-<迭代标识> (如 develop/20250601-s14)
• 创建方式：从 master 分支切出
• 作用：单个项目/迭代周期的开发主线
• 生命周期：
  • 创建：迭代启动时
  • 删除：保留10个历史迭代
• 合并规则：
  • 接受来自 feature/xxx 分支的 Merge Request

3. 功能分支 (feature/xxx)

• 命名规范：feature/<date>-<功能描述> (如 feature/20250603-user-auth)
• 创建方式：从 develop/xxx 分支切出
• 作用：单个功能/模块的开发
• 生命周期：
  • 创建：功能开发开始时
  • 删除：功能发布到预发环境后
• 操作规范：
  • 每天至少 rebase 一次 develop/xxx 分支
  • 功能完成并通过自测后发起 Merge Request

4. 发布分支 (release/xxx)

• 命名规范：release/<date>-<版本号> (如 release/20250625-1.2.0)
• 创建方式：从 master 分支切出
• 作用：版本发布准备
• 操作流程：
  1. 从 master 切出 release 分支
  2. 合并对应 develop/xxx 分支
  3. 进行预发布测试和修复
  4. 合并到 uat 分支进行用户验收测试
  5. 测试通过后合并到 master
• 保护规则：
  • 只接受来自 develop/xxx 的 Merge Request
  • 只能合并到 master 和 uat

5. 热修复分支（hotfix/xxx）

• 命名规范：hotfix/<date>-<问题描述> (如 hotfix/20250630-payment-bug)
• 创建方式：从 master 分支切出
• 作用：线上问题修复
• 操作流程：
  1. 从 master 切出 hotfix 分支
  2. 进行BUG修复
  3. 提交 Merge Request
  4. 修复后合并到 develop/xxx 分支
• 保护规则：
  • 只能合并到 master 和 develop/xxx

6. 环境部署分支

分支类型	分支名	环境	更新来源	自动部署规则
开发环境	develop	开发环境	develop/xxx 合并	每次 push 自动部署
测试环境	test	测试环境	develop/xxx 分支合并	每次 push 自动部署
UAT环境	uat	UAT环境	release/xxx 合并	手动触发部署

工作流程详解

新功能开发流程

提测流程

版本发布流程

热修复流程

分支命名规范

分支类型	命名模式	示例
项目迭代分支	develop/<date>-s<storyid>	develop/20250601-s14
功能分支	feature/<date>-<description>	feat/20250603-user-authentication
发布分支	release/<date>-<version>	release/20250625-1.2.0
热修复分支	hotfix/<date>-<issue>	hotfix/20250630-login-error

权限控制

Git 仓库权限矩阵

操作	开发者	技术主管	运维工程师
创建 feature/xxx 分支	✓	✓	✗
合并到 develop/xxx	✗	✓	✗
创建 release/xxx 分支	✗	✓	✓
合并到 master	✗	✓	✓
创建 hotfix 分支	✗	✓	✓
删除分支	✗	✓	✓

Merge Request 规则

1. 最小审批人数：

   • feature → develop/xxx：1人（主R）
   • develop/xxx → release/xxx：1人（主R）
   • release/xxx → master：2人（含1名运维，暂由主R执行）
   • hotfix/xxx → master：2人（含1名运维，暂由主R执行）
   • hotfix/xxx → develop/xxx: 1人（主R）

2. 必需检查：

   • 所有测试用例通过
   • 代码覆盖率不低于 80%
   • 静态代码分析无严重问题
   • 无合并冲突

CI/CD 集成规范

流水线触发规则

分支类型	触发动作	执行任务	是否实现
feature/xxx	push	单元测试、代码扫描	✗
develop/xxx	merge request	集成测试、Docker 构建	✗
develop	push	部署开发环境、API 文档生成	✗
test	push	部署测试环境、自动化测试	✗
release/xxx	push	预发布构建、安全扫描	✗
uat	merge request	部署UAT环境、性能测试	✗
master	merge request	生产构建、部署生产、版本标记	✗
hotfix/xxx	push	紧急测试套件、快速部署检查	✗

---

最佳实践

建议用图形界工具面操作分支

• IDEA
• SOURCETREE
• 小乌龟
• Gitkraken

1. 分支管理

• 使用 git fetch --prune 定期清理本地缓存
• 删除已合并的分支：git branch --merged | grep -v master | xargs git branch -d
• 使用交互式 rebase 清理提交历史：git rebase -i HEAD~5

2. 提交规范

• 遵循 Conventional Commits 规范：

<类型> [<时间>]: <描述>

[可选 正文]

[可选 脚注]

• 类型可参考：https://gitmoji.js.org/
• IDEA插件推荐：Open Gitmoji

示例：

git commit -m "✨ [2025-06-01]: add OAuth2 support

- Implement Wework OAuth2 provider
- Add token refresh mechanism

Closes #123"

或者

git commit -m ":sparkles: [2025-06-01]: add OAuth2 support

- Implement Wework OAuth2 provider
- Add token refresh mechanism

Closes #123"

3. 版本管理

• 主版本 (Major)：不兼容的 API 修改
• 次版本 (Minor)：向下兼容的功能新增
• 修订号 (Patch)：向下兼容的问题修正

使用语义化版本标签：

git tag -a 1.2.3 -m "Release sso module"
git push origin 1.2.3

4. 冲突解决

优先在功能分支解决：

git checkout feature/xxx
git fetch origin
git rebase origin/develop/xxx
#- 解决冲突
git rebase --continue

建议用工具解决冲突

• idea
• vscode
• sourcetree
• 小乌龟
• 等等

附录：常用命令参考

分支操作

#- 创建迭代分支
git checkout -b develop/20260601-s14 master

#- 创建功能分支
git checkout -b feature/20260603-user-auth develop/20260601-s14

#- 每日同步
git fetch origin
git rebase origin/develop/20260601-s14

#- 提交变更
git add .
git commit -m "✨ [2025-06-01]: add OAuth2 support"

#- 推送功能分支
git push -u origin feature/20260603-user-auth

#- 清理分支
git branch -d feature/20260603-user-auth

发布操作

#- 创建发布分支
git checkout -b release/20250625-1.2.0 master

#- 合并开发分支
git merge --no-ff develop/20260601-s14

#- 解决冲突并提交
git add .
git commit -m "Merge develop/20260601-s14 into release/20250625-1.2.0"

#- 测试后合并到master
git checkout master
git merge --no-ff release/20250625-1.2.0
git tag -a 1.2.0 -m "Release 1.2.0"

热修复

#- 创建热修复分支
git checkout -b hotfix/20250630-login-error master

#- 修复问题并提交
git add .
git commit -m "🐛 [2025-06-30]: 修复用户数据为空引起的空指针异常"

#- 测试后合并到master
git checkout master
git merge --no-ff hotfix/20250630-login-error
git tag -a 1.2.1 -m "Hotfix for login issue"

#- 合并到develop
git checkout develop/xxx
git merge --no-ff hotfix/20250630-login-error

#- 清理
git branch -d hotfix/20250630-login-error