跳至主要內容

ADC 项目 Git 分支与发布流程规范

2026/9/19大约 14 分钟

ADC 项目 Git 分支与发布流程规范

文档版本：v1.1
适用范围： ADC 业务代码仓库的日常开发、测试、预发布、生产发布及线上紧急修复。
核心发布链路： dev → test → preprod → main

1. 目标

本规范用于统一团队 Git 分支管理和版本发布流程，确保：

  • 开发、测试、预发布、生产环境代码边界清晰；
  • 新功能和 Bug 修复有明确的流转路径；
  • 生产代码始终可追溯；
  • 线上紧急问题能够快速修复，并确保修复同步回开发线；
  • 长期分支统一通过 PR 流转；
  • 测试、预发布、生产环境通过 Jenkins CI/CD 发布；
  • 提供实践说明，参考具体场景直接执行，而不需要自行判断应该从哪个分支开始。

2. 分支模型

2.1 长期分支

分支定位对应环境说明
dev开发集成分支开发环境已完成开发、准备联调和进入测试的代码
test测试分支测试环境QA、功能测试、回归测试使用
preprod预发布分支预发布环境生产发布前最终验证
main生产分支生产环境当前正式生产代码基线

正常代码流转：

原则上不允许反向使用环境分支进行日常开发。

2.2 临时分支

分支用途从哪里创建完成后
feature/*新功能开发devPR 合并到 dev 后删除
bugfix/*普通 Bug 修复devPR 合并到 dev 后删除
hotfix/*生产紧急修复main发布并同步 dev 后删除

推荐命名：

feature/approval-flow
feature/ADC-1024-user-import
bugfix/ADC-1058-user-avatar
hotfix/login-token-error

如果有需求单或缺陷编号，建议带上编号。

3. 必须遵守的基本原则

  1. dev、test、preprod、main 均为长期分支，不删除。
  2. 新功能从最新 dev 创建 feature/*。
  3. 普通 Bug 从最新 dev 创建 bugfix/*。
  4. 生产紧急 Bug 从最新 main 创建 hotfix/*。
  5. 正常发布只能按照 dev → test → preprod → main 向前流转。
  6. 长期分支禁止 Force Push。
  7. 长期分支不直接开发，统一通过 PR 合并。
  8. test、preprod、main 不作为普通开发分支使用。
  9. Hotfix 上线后必须同步回 dev。
  10. 测试、预发布、生产环境原则上由 Jenkins 发布，不手工 SSH 修改服务器代码。

4. 先记住：Pull、Commit、Push、PR 分别是什么

操作作用是否发布环境
git pull获取远程最新代码否
git commit保存本地代码版本否
git push把当前开发分支提交到 Gitea通常否
创建 PR请求把来源分支合并到目标分支取决于目标分支
Merge PR代码真正进入目标长期分支可能触发 Jenkins

重点：Push Feature 分支不是发布。

5. 场景一：开发一个新需求

假设需求为：ADC-1024 新增合同审批功能。

5.1 开始开发前：更新 dev

git checkout dev
git pull origin dev

然后从最新 dev 创建 Feature：

git checkout -b feature/ADC-1024-contract-approval

创建 Feature 前先 Pull，避免基于本地旧版 dev 开发。

5.2 开发、Commit、Push

git add .
git commit -m "feat(ADC-1024): 新增合同审批功能"
git push -u origin feature/ADC-1024-contract-approval

后续继续开发：

git add .
git commit -m "feat(ADC-1024): 完善合同审批流程"
git push

开发期间可以多次 Commit 和 Push。

5.3 开发完成后创建 PR

在 Gitea 创建：

  • Source： feature/ADC-1024-contract-approval
  • Target： dev

PR 合并后 Feature 分支即可删除。

示例图：

image-20260920144937038

image-20260920145037696

6. PR 应该写什么

PR 至少说明：

  • 修改内容；
  • 需求/缺陷编号；
  • 是否涉及数据库 Migration；
  • 是否涉及配置或环境变量；
  • 是否涉及第三方服务；
  • 是否存在兼容性风险；
  • 如何验证；
  • 生产相关修改必要时说明回滚方式。

示例：

需求：ADC-1024 合同审批

主要修改：
1. 新增合同审批接口
2. 新增审批记录
3. 增加审批状态流转

数据库变更：有
环境变量：无

验证方式：
1. 创建合同
2. 提交审批
3. 审批通过
4. 查询审批结果

7. Commit Message 规范

采用 Conventional Commits：

feat:     新功能
fix:      Bug 修复
refactor: 代码重构
perf:     性能优化
docs:     文档修改
test:     测试相关
chore:    工程、依赖、构建调整

推荐：

feat(ADC-1024): 新增合同审批功能
fix(ADC-1058): 修复用户头像显示异常

不推荐：

修改
修复bug
update
111
test

8. 场景二：发布测试环境

当一批功能已经进入 dev，开发和联调完成后，由负责人创建：

  • Source： dev
  • Target： test

PR Review 后 Merge。

8.1 Jenkins 什么时候触发？

dev → test 的 PR 创建本身不会发布测试环境。

真正的测试部署触发点是：代码 Merge 到 test，导致 test 分支更新。

因此开发人员不要手工 SSH 到测试服务器执行 git pull 或替换代码。

test 分支应当代表当前测试环境的代码基线。

9. 场景三：测试环境发现普通 Bug

QA 在测试环境发现 Bug 时，不要直接修改 test。

从最新 dev 创建 Bugfix：

git checkout dev
git pull origin dev
git checkout -b bugfix/ADC-1058-approval-status

修复后：

git add .
git commit -m "fix(ADC-1058): 修复合同审批状态异常"
git push -u origin bugfix/ADC-1058-approval-status

然后创建 bugfix/* → dev PR。

这样可以避免 Bug 只在 test 修复，而 dev 仍保留旧问题。

10. 场景四：测试通过，发布预发布环境

测试通过后创建：

  • Source： test
  • Target： preprod

预发布重点验证：

  • 本次待发布功能是否完整；
  • 回归测试；
  • Migration；
  • 环境变量和配置；
  • 第三方接口；
  • Redis、RabbitMQ、文件存储等外部依赖；
  • 前后端生产前构建；
  • 多服务联调；
  • 部署脚本。

preprod 应保持相对稳定。进入 preprod 后原则上不要继续塞入与本次发布无关的新需求。

11. 预发布发现 Bug 怎么办

普通问题仍然回开发线修复，不直接在 preprod 修改。

如果已经进入预发布的版本发现问题，修复仍需保证最终存在于 dev，然后重新逐级晋升。

12. 场景五：预发布通过，准备发布生产

预发布验证通过后创建：

  • Source： preprod
  • Target： main

12.1 main 与其他长期分支的区别

目前只有 main 要求 Jenkins PR Status Check。

例如 adc-hr：

不同仓库使用自己的 Status Context：

adc-user → jenkins/adc-user-pr-check
adc-hr   → jenkins/adc-hr-pr-check
adc-crm  → jenkins/adc-crm-pr-check

当前 required_approvals = 0，表示 Gitea 不强制要求固定数量的人工 Approve；但团队仍可按实际需要进行 Code Review。

13. PR Check 与生产发布不是一回事

需要特别区分：

PR Check： 判断代码是否满足进入 main 的条件。
Production Pipeline： 把已经进入 main 的版本发布到生产环境。

14. Git Tag 与生产版本

正式生产发布成功后，由 Jenkins 创建 Git Tag，用于定位真实生产版本。

当前采用日期版本：

v2026.09.20
v2026.09.20.1
v2026.09.20.2

开发人员原则上不要手工给生产版本打 Tag。

15. 场景六：普通 Bug 修复

不是生产紧急事故的 Bug，一律走开发线：

创建：

git checkout dev
git pull origin dev
git checkout -b bugfix/ADC-1058-user-avatar

不要为了普通 Bug 绕过环境分支直接修改生产。

16. 场景七：生产紧急 Bug / Hotfix

生产发生严重问题时，不从 dev 创建修复分支，因为 dev 可能包含尚未发布的新功能。

先更新 main：

git checkout main
git pull origin main
git checkout -b hotfix/login-token-error

修复并 Push：

git add .
git commit -m "fix: 修复登录 Token 失效问题"
git push -u origin hotfix/login-token-error

16.1 Hotfix 发布

有时间时尽量进行测试/预发布验证；P0/P1 严重事故可缩短验证周期，但至少完成最小必要验证。

17. Hotfix 上线后必须回合 dev

这是 Hotfix 最容易遗漏的一步。

Hotfix 发布后必须同时保证开发线包含这个修复。

否则会出现 main 已修复、dev 仍有旧 Bug，后续正常发布可能再次把问题带回生产。

Hotfix 同步 dev 完成后再删除 Hotfix 分支。

18. 每天继续开发时应该 Pull 哪个分支？

开始一个新需求

git checkout dev
git pull origin dev
git checkout -b feature/ADC-1100-xxx

继续自己已有的 Feature

git checkout feature/ADC-1024-contract-approval
git pull

如果 Feature 开发周期较长，需要同步最新 dev：

git checkout dev
git pull origin dev

git checkout feature/ADC-1024-contract-approval
git merge dev

19. PR 冲突怎么处理

核心原则：

冲突统一在 PR 来源分支解决，不直接 Push 目标长期分支。

19.1 Feature → dev 冲突

例如：feature/approval-flow → dev。

git checkout dev
git pull origin dev

git checkout feature/approval-flow
git merge dev

使用 JetBrains IDE 或其他工具 解决冲突，然后：

git add .
git commit
git push origin feature/approval-flow

19.2 环境晋升 PR 冲突

来源分支吸收目标分支的最新代码：

不要为了处理冲突直接 Push test、preprod 或 main，这些分支已禁止推送 也禁止强制推送。

19.3 Hotfix → dev 回合冲突

git checkout dev
git pull origin dev

git checkout hotfix/login-token-error
git merge dev

解决后：

git add .
git commit
git push origin hotfix/login-token-error

继续使用原 hotfix/* → dev PR。

20. 发布批次管理

test 中的代码原则上应该属于同一个待发布批次。

例如：功能 A 已通过、功能 B 测试失败、功能 C 尚未测试，此时如果整体执行 test → preprod，B 和 C 也会被带入预发布。

因此进入 test 前，应尽量确认本批功能属于同一发布批次。

如果未来长期存在多个版本并行测试、部分功能延期、多个发布窗口并行，再考虑引入 release/*，当前阶段不增加额外长期分支。

21. CI/CD 与分支对应关系

Git 分支环境当前主要行为
dev开发集成根据项目需要
test测试环境Merge/Push 后 Jenkins 自动部署
preprod预发布环境受控 Jenkins 部署
main生产环境PR Check + 受控生产发布

前端构建模式：

test    → vite build --mode test
preprod → vite build --mode preprod
main    → production build

整体触发关系：

22. 长期分支保护策略

当前长期分支：

dev
test
preprod
main

统一原则：

操作devtestpreprodmain
直接 Push禁止禁止禁止禁止
PR 合并是是是是
Force Push禁止禁止禁止禁止
Jenkins Status Check不强制不强制不强制强制
Required Approvals0000
管理员绕过保护禁止禁止禁止禁止

main 的 Status Context 按仓库动态生成：

jenkins/${repo}-pr-check

例如：

jenkins/adc-hr-pr-check
jenkins/adc-user-pr-check
jenkins/adc-crm-pr-check

23. 实践完整场景：一个需求从接手到生产

下面是最需要掌握的一张图。

24. 操作速查表

场景从哪里开始PR 流程Jenkins
新需求dev → feature/*feature/* → dev不直接发布环境
普通 Bugdev → bugfix/*bugfix/* → dev不直接发布环境
发布测试devdev → testMerge 后自动部署测试
发布预发布testtest → preprodMerge 后受控部署预发布
发布生产preprodpreprod → mainPR Check + 生产 Pipeline
生产 Hotfixmain → hotfix/*hotfix/* → mainPR Check + 生产 Pipeline
Hotfix 回合hotfix/*hotfix/* → dev回到正常开发线

25. 常见错误

正确原则：

26. 最终分支关系

27. 核心规则速记

  1. 新功能：dev → feature/*。
  2. 普通 Bug：dev → bugfix/*。
  3. 生产紧急 Bug：main → hotfix/*。
  4. 正常发布：dev → test → preprod → main。
  5. 长期分支通过 PR 流转，不直接开发。
  6. test 更新后触发 Jenkins 测试环境自动部署。
  7. preprod 是生产候选版本。
  8. main PR 必须通过对应仓库 Jenkins PR Check。
  9. 生产发布成功后由 Jenkins 创建 Git Tag。
  10. Hotfix 上线后必须回合 dev。
  11. PR 冲突在来源分支解决。
  12. 禁止长期分支 Force Push。

文档版本：v1.2
适用分支：dev / test / preprod / main
适用对象：开发人员、测试人员、技术负责人、发布负责人

贡献者

yangzai
最近更新: