Git 分支管理规范与流程指南

命名示例

feature/{jira}-add-something
feature/{jira}/{username}-add-something
hotfix/{jira}-fix-something
hotfix/{jira}/{username}-add-something
adhoc/{jira}-fix-something
adhoc/{jira}/{username}-fix-something
bugfix/{jira}-fix-something
bugfix/{jira}/{username}-fix-something
version/[uat/release]-${YYMMDD}
temp/temp/{jira}-{username}-${YYMMDDHHMM}
tag-${YYMMDD}-v{num}

建议在本地安装 Git Hook 来确保分支命名规范得到执行。

四、分支管理

1. 创建分支

1.1 release 分支是基线分支（也可能是 master 分支，此处以 release 作为示例）

由于 release 分支对应线上，平时开发需求、紧急修复都要从基于 release 分支进行。

1.2 开发分支的创建（feature & dev）

在进行功能开发时，需要创建对应的开发分支。在开发分支上可以自由尝试各种实现方案，开发分支上的任何改动都不会影响到主干分支，因此可以安全地进行实验或提交改动。当准备将代码合并到主干分支时，需要请团队成员进行代码审查。 如果使用任务管理系统（如 Jira）来管理工作内容，并且采用 sub-task 的方式进行任务分解，那么分支命名应该与任务管理系统中的内容保持对应关系。

• feature 分支的创建：基于 release 分支创建 feature 分支。
• dev 分支的创建：基于 feature 分支创建 dev 分支。

注意：即使是一个人开发或者只有一个 sub-task，也尽量去创建 dev 分支。

1.3 Jira（工作任务）与 Git（分支）的对应关系

• 和 Jira task 对应的是 feature 分支
• 和 sub-task 对应的是 dev 分支

1.4 特殊情况

当开发的需求依赖于另一个尚未上线的需求（例如该需求仍在 UAT 环境测试中）时，仍然需要从 release 分支创建 feature 分支，然后将被依赖的分支合并进来，基于合并后的分支进行开发。 注意：如果被依赖的 feature 存在发布延期或取消的风险，可能会导致当前 feature 无法按时发布，应尽量避免此类依赖关系。

2. 代码 Commit

• 创建分支后，即可开始进行代码修改。在 feature 分支上进行文件的新增、编辑或删除操作时，都应该及时提交 Commit，这样可以清晰地跟踪开发进度。
• 每次 Commit 都会在版本历史中留下记录，有助于团队成员理解代码变更的原因和目的。每个 Commit 都应该包含清晰的提交信息（建议带上 jira 号，方便回溯），说明本次改动的具体内容和原因。
• 建议将每个 Commit 作为一个独立的、可回滚的单元。这样的设计有助于在发现 bug 或需要回退到某个历史版本时，能够精确地定位和恢复代码。

git commit -m "{jira}-add-some-logic"

3. 代码 Push

完成代码编写和本地自测后，可以将代码推送到远程仓库的 dev 分支。

git push origin feature/{jira}/{username}-fix-something

禁止使用'-force'的方式强制提交代码到远程分支。

4. 代码 Merge Request（MR）

• 功能开发完成后，需要创建 MR 将 dev 分支的代码合并到 feature 主分支。
• 在合并到主分支之前，团队成员可以通过 MR 进行代码审查，并提出改进建议。
• MR 的描述需要包含对应的 jira 号。
• 只有 MR 记录需要保留，详细的 commit 历史可以通过 GitLab 配置进行管理。

重要提示：合并到其他分支的代码必须是可运行的完整功能，不能包含编译错误或运行时错误。

4.1 冲突的解决

代码冲突通常发生在以下场景：

• 多人协作开发同一需求时，不同开发者修改到同一块代码，因此产生代码冲突
• Feature 分支在开发过程中，若 release 分支更新，将 release 合并到 feature 分支时有可能产生代码冲突

冲突解决的基本原则：

1. 需与相关开发者协作，禁止单方面处理冲突
2. 尽早解决，避免问题累积
3. 不可随意拉取：拉取目标分支代码前，需确认其代码可同步发布
4. 解决后仔细核查，避免遗漏多冲突点与代码错误
5. 完成后必须重新执行自测与 mock 测试，确保功能正常

5. Code Review（CR）

• 功能开发完成拟合并至 feature 分支时，需进行完整的代码审查（可指定模块 / 项目负责人参与），该环节既是代码质量把关手段，也是团队讨论技术方案与实现细节的技术交流平台
• 审查人员需对代码质量负责，需细致核查代码逻辑、规范性及潜在问题，不可草率点击合并

6. Feature 开发完成后提测

当功能开发完成且通过自测后，dev 将 feature 分支合并到 test 分支，然后交由 QA 测试。 注意：为了避免测试过程中不同需求之间可能会相互影响，流程已更新为'将 feature 分支合并到 pfb 分支，QA 在 pfb 环境上测试（一个需求可相应的去新建一个 pfb 环境）'

6.1 冲突的解决

将 feature 分支提 MR 到 test 分支时候可能会有冲突，但 test 分支包含了与该 feature 不一起发布的分支。

如果有冲突，参考下面的做法： 从 test 分支 checkout 一个 temp 分支 => 将 feat 分支合并到 temp 分支 => 在 temp 分支上解决掉冲突 => 将 temp 分支合并到 test 分支

7. Feature 开发完成后交付 UAT

当功能 QA 测试完成后，交由业务进行 UAT 测试：

7.1 冲突的解决

如果有冲突，参考下面的做法： 从 uat 分支 checkout 一个 temp 分支 => 将 feat 分支合并到 temp 分支 => 在 temp 分支上解决掉冲突 => 将 temp 分支合并到 uat 分支

8. Testing 或者 UAT 过程的修复 bug

Feature 提交测试后，QA 进行测试会提的 testing 的 bug；交付 UAT，业务会提 UAT 的 bug，可直接在 dev 分支上进行修复，验证通过后再合并到 test or uat 分支（dev 自测 + QA 测试） 另外情况，如果有些 bug 不立马修复，不跟这个 feature 一起上线，操作为：这个 bug 单独一个 bugfix 分支，后续跟着版本或者独立上线即可。

9. 发布

在版本发布流程中，通常在发布前才能最终确定本次发布包含的功能。确定版本内容后，需要将所有相关的 feature 分支进行合并（解决可能存在的冲突），完成回归测试，然后创建 tag 并进行发布。

9.1 Create Version Branch 创建版本分支

9.1.1 冲突的解决

如果冲突解决的方法如下： 从 release 分支 checkout 一个 temp 分支 => 将 feat 分支合并到 temp 分支 => 在 temp 分支上解决掉冲突 => 将 temp 分支合并到 version 分支

9.2 回归测试

将 version 分支部署在 staging 环境，即可开始回归测试

9.3 合并 release 发布

• 将 version 分支提 MR 到 release 分支（包括本次需要发版的所有需求）
• 根据审计要求，发布必须打 tag 来发布，合并到 release 分支后，打 tag 就可以了。

git tag tag-20260118-v1

9.3.1 冲突的解决

这个时候如果有冲突（很少发生），说明在 version 分支创建之后，release 分支有了更新，这个时候需要： 将 release 分支合并到该 version 分支 => 解决冲突 => 重新测试该 version 分支 => 测试通过后，将该 version 分支合并到 release 分支，进行打 tag 发布

9.4 基线 (release) 分支的重置

由于所有开发分支都基于 release 分支创建，当新版本发布后，release 分支会发生变化（相对于之前创建开发分支时的状态）。因此，需要将更新后的 release 分支合并到当前正在开发的分支，这个过程称为基线分支重置。

基线重置过程可以通过自动化工具辅助完成。当 release 分支发生变更并发布到生产环境后：

• 自动化工具会创建 MR 到保护分支（test/uat/master），需要开发人员手动处理合并
• 自动化工具会在客户端通过 githooks 进行检测，提醒开发人员及时重置基线分支
• 当 feature 分支创建 MR 到保护分支时，系统也会提醒开发人员检查并重置基线分支

9.5 发布失败 Fail to release

• 如果发布失败，应用做回滚之后，代码也要记得做回滚
• 发布失败，要周知到所有人：合作方（互相有依赖）、团队（中间可能有人拉了分支）
• 继续发布：先剔除或修复有 bug 的分支再做发布
• 保证线上的代码和 git 的代码一致

10. 额外的流程 1-Live bug 修复

当生产环境出现 bug 需要修复时，修复流程与 feature 开发流程基本一致，区别在于使用 bugfix 类型的分支来标识这是 bug 修复任务，后续的测试、审查和发布流程与 feature 开发保持一致。

11. 额外的流程 2-hotfix

当生产环境出现严重问题需要紧急修复时，采用 hotfix 流程。 处理流程：从 release 分支创建 hotfix 分支，进行问题修复 => 在 staging 环境对 hotfix 分支进行验证 => 验证通过后，将 hotfix 分支合并到 release 分支并发布

12. 额外的流程 3-adhoc

当业务出现紧急问题或需求，需要快速上线时，采用 adhoc 流程。 处理流程：从 release 分支创建 adhoc 分支，进行紧急开发或修复 => 在 staging 环境对 adhoc 分支进行验证 => 验证通过后，将 adhoc 分支合并到 release 分支并发布

13. 额外的流程 4-发布回滚

发布回滚到某个 tag 后，如果可以紧急修复问题，可以走 hotfix 流程，但是如果无法快速恢复，需要先将 release 和其他相关分支的代码回滚到对应 tag 的改动，并且需要重新验证。

14. 冲突的解决

冲突解决原则

1. 协作解决：需与产生冲突的开发者共同协商处理，禁止单方面决定冲突代码的处置方案。
2. 及时处理：尽早解决冲突，避免问题累积影响开发进度。
3. 分支隔离：不随意拉取目标分支代码，需先评估其是否包含可同步发布的代码；尤其注意 test、uat 等环境分支易包含多功能代码，直接拉取会造成分支污染，仅可拉取确认可共同发布的代码。
4. 质量验证：冲突解决后，需通过人工 + IDE / 代码检查工具等核查所有冲突点（如<<<标记）与代码错误，无遗漏后重新执行自测和 mock 测试，确保功能无异常。
5. 问题溯源：冲突频发需分析根源，排查不规范分支操作，同时评估代码耦合度，对高耦合模块进行适当拆分

15. 分支的管理和维护

• 已发布到生产环境的 feature、hotfix、adhoc、bugfix 分支，建议每 3 个月定期清理。如有特殊需要保留的分支，可以设置为保护分支。
• 已发布到生产环境的 dev 分支和版本分支，建议每 1 个月定期清理。
• 已上线的 feature 分支不允许再进行任何修改，如需修改应创建新的分支。

五、注意事项 Matters need attention

• version 分支也属于保护分支
• 所有的保护分支（release 除外）只能 Merge，而不能合并到开发分支（feature，hotfix，bugfix）
• 目前有些项目有特殊环境配置（如 stable 环境），业务项目组自行维护处理，可以与自动化系统集成做一些 release 分支重建的工作。

六、工作流程图

6.1 Feature 开发流程

release 分支 ↓ feature/{jira}-add-something (创建 feature 分支)
↓ feature/{jira}/{username}-add-something (创建 dev 分支)
↓ 开发、提交、MR 到 feature 分支
↓ Code Review
↓ feature 分支 MR 到 test / pfb 分支 (提测)
↓ QA 测试
↓ feature 分支 MR 到 uat 分支 (UAT 测试)
↓ 业务 UAT 测试
↓ 创建 version 分支，合并多个 feature
↓ 回归测试
↓ version 分支 MR 到 release 分支
↓ 打 tag 发布

6.2 Bugfix 流程

release 分支 ↓ bugfix/{jira}-fix-something (创建 bugfix 分支)
↓ 修复、测试
↓ bugfix 分支 MR 到 test/uat 分支
↓ 测试通过后，跟随版本发布

6.3 Hotfix 流程

release 分支 ↓ hotfix/{jira}-fix-something (创建 hotfix 分支)
↓ 修复
↓ staging 环境验证
↓ hotfix 分支 MR 到 release 分支
↓ 打 tag 紧急发布

6.4 Adhoc 流程

release 分支 ↓ adhoc/{jira}-add-something (创建 adhoc 分支)
↓ 开发
↓ staging 环境验证
↓ adhoc 分支 MR 到 release 分支
↓ 打 tag 紧急发布

七、关键要点总结

7.1 分支创建原则

• ✅ 所有开发分支都基于 release 分支创建
• ✅ feature 分支对应 Jira Task
• ✅ dev 分支对应 Jira Sub-task
• ✅ 一个人开发也要创建 dev 分支

7.2 冲突解决原则

• ✅ 协作解决
• ✅ 及时处理
• ✅ 分支隔离
• ✅ 质量验证
• ✅ 问题溯源

7.3 发布流程要点

• ✅ 版本发布前必须创建 version 分支
• ✅ 必须进行回归测试
• ✅ 必须打 tag 才能发布
• ✅ 发布失败必须回滚代码
• ✅ release 分支变更后需要重置开发分支基线

7.4 分支维护要点

• ✅ 线上分支 3 个月定期清理（feature、hotfix、adhoc、bugfix）
• ✅ dev 分支和版本分支 1 个月定期清理
• ✅ 已上线的 feature 分支不允许再修改