分支最佳实践

分支管理

概述

本文档规定了项目的分支管理策略和工作流程。

分支模型

环境分支

分支名称	环境	说明
master	生产环境	稳定版本，已上线的代码
release	UAT 环境	用户验收测试，预发布版本
test	测试环境	测试团队使用
develop	开发环境	开发团队集成环境

功能分支命名规范

[feat/fix]-[发布日期]-[功能描述]

示例:

feat-1025-purchase-order       # 新增采购单功能
feat-20241025-supplier-import  # 新增供应商导入（完整日期）
fix-1023-login-error           # 修复登录错误

规则:

• feat - 新功能，fix - Bug 修复
• 日期格式：MMDD 或 YYYYMMDD
• 功能描述使用英文或拼音，用 - 连接

工作流程

1. 创建功能分支

⚠️ 必须从 master 分支切出

# 更新 master
git checkout master
git pull origin master

# 创建功能分支
git checkout -b feat-1025-purchase-order
git push -u origin feat-1025-purchase-order

2. 开发和提交

git add .
git commit -m "feat(purchase): 新增采购单列表页面"
git push origin feat-1025-purchase-order

3. 创建 Merge Request

在 GitLab 上创建 MR：

• 源分支: feat-1025-purchase-order
• 目标分支: 根据部署环境选择 develop / test / release / master
• 指定审批人: 至少 1 名代码审查人
• 填写说明: 功能描述、测试说明、关联 Issue

4. 代码审查

审批人检查代码质量，通过后合并。

5. 合并分支

审批通过后，在 GitLab 点击 "Merge" 按钮。

合并后清理：

# 删除远程分支
git push origin --delete feat-1025-purchase-order

# 删除本地分支
git checkout master
git branch -d feat-1025-purchase-order

分支保护规则

⚠️ 严禁操作

❌ 不允许将环境分支合并到功能分支（会造成分支污染）

# ❌ 严禁
git checkout feat-1025-purchase-order
git merge develop  # 严禁！
git merge test     # 严禁！
git merge release  # 严禁！

❌ 不允许从环境分支切出功能分支

# ❌ 严禁
git checkout develop
git checkout -b feat-1025-purchase-order  # 严禁！

✅ 正确的同步方式

如需同步 master 最新代码：

方案一：Rebase（推荐）

git checkout master
git pull origin master

git checkout feat-1025-purchase-order
git rebase master

# 解决冲突后
git push origin feat-1025-purchase-order --force-with-lease

方案二：Merge master

git checkout master
git pull origin master

git checkout feat-1025-purchase-order
git merge master

# 解决冲突后
git push origin feat-1025-purchase-order

环境部署流程

功能按以下顺序部署：

功能分支 → develop → test → release → master

1. 开发环境 (develop) - 开发团队自测
2. 测试环境 (test) - 测试团队完整测试
3. UAT 环境 (release) - 用户验收测试
4. 生产环境 (master) - 发布上线

紧急修复 (Hotfix)

# 从 master 切出修复分支
git checkout master
git pull origin master
git checkout -b fix-1025-urgent-bug

# 修复并提交
git add .
git commit -m "fix(system): 修复生产环境紧急问题"
git push origin fix-1025-urgent-bug

# 创建 MR 到 master，并同步到其他环境分支

⚠️ Hotfix 需要同步到所有环境分支

版本发布

版本号规范

采用语义化版本号：v<major>.<minor>.<patch>

• v1.0.0 - 首个正式版本
• v1.1.0 - 新增功能
• v1.1.1 - 修复 Bug
• v2.0.0 - 重大更新，可能不兼容

打标签

发布到生产环境时，在 GitLab 上为 master 分支打标签：

在 GitLab 创建 Tag:

1. 访问 Repository → Tags
2. 点击 New tag 按钮
3. 填写标签信息：
   • Tag name: v1.2.0
   • Create from: master
   • Message: 版本说明
   • Release notes: 详细的功能说明和 Bug 修复列表
4. 点击 Create tag

命令行方式（可选）:

git checkout master
git pull origin master

# 创建标签
git tag -a v1.2.0 -m "Release version 1.2.0"

# 推送标签
git push origin v1.2.0

分支清理

定期清理已合并的功能分支：

# 查看已合并的本地分支
git branch --merged master

# 删除已合并的本地分支
git branch --merged master | grep -v "master\|develop\|test\|release" | xargs git branch -d

# 清理远程分支引用
git remote prune origin

建议: 在 GitLab MR 设置中启用 "Delete source branch when merge request is accepted"

最佳实践

✅ 推荐

1. 频繁提交，清晰的提交信息
2. MR 保持小而频繁，便于审查
3. 定期从 master 同步最新代码
4. 认真进行 Code Review
5. 合并前确保测试通过

❌ 避免

1. 从 develop/test/release 切出功能分支
2. 将 develop/test/release 合并到功能分支
3. 直接 push 到环境分支
4. 跳过 Code Review
5. 长期不合并的大型功能分支