Main 正式环境合并说明

本文档说明测试通过后，如何将开发分支通过 Merge Request（MR）合入 main。

总流程： $Git 分支开发指南$
测试环境： $Develop 测试环境合并说明$
冲突协助： $Git 冲突与 AI 协助指南$

Main 是什么

main 对应正式环境，只接收已经测试并允许上线的需求。

正式发布的固定方向是：

text 复制代码

开发分支 → MR → main

禁止：

text 复制代码

develop → main

因为 develop 可能同时包含多个状态不同的需求：

text 复制代码

develop
├── 需求 A：测试通过
├── 需求 B：测试中
└── 需求 C：存在问题

如果只有 A 可以上线，就只能用需求 A 的开发分支向 main 发起 MR。将整个 develop 合入 main 会把 B、C 一起带入正式环境。

下文命令中的 <开发分支> 是占位符，需要替换为真实分支名。

创建 Main MR

确认当前需求已经在 develop 对应的测试环境通过验证，并且开发分支的提交均已推送：

bash 复制代码

git switch <开发分支>
git status
git push

然后在代码平台创建：

text 复制代码

Source: <开发分支>
Target: main

合并前依次检查：

Source 是当前需求的开发分支。
Target 是 main。
Diff 只包含当前需求。
CI 和构建成功。
测试已经通过。
MR 没有未处理的冲突。
正式审核已经通过。

以上条件都满足后才能合并。

冲突处理

Main MR 为什么会冲突

开发分支从 main 创建以后，可能有其他需求先上线，使远端 main 发生变化：

text 复制代码

main ──→ 创建开发分支 A
  │
  └────→ 需求 B 先上线并修改了相同代码

此时 A 再向 main 发起 MR，Git 可能无法自动组合两边修改。

正确处理方向

main 冲突必须在自己的开发分支处理：

text 复制代码

最新 main → 开发分支
                  │
                  ├── 解决冲突
                  ├── 推送开发分支
                  └── 重新合入 develop 测试

不要将 develop 合入开发分支。

获取最新 main 并开始合并

先确认开发分支工作区没有未提交修改：

bash 复制代码

git switch <开发分支>
git status

获取远端最新状态，并将最新 main 合入当前开发分支：

bash 复制代码

git fetch origin
git merge origin/main

没有冲突时，Git 会直接完成合并。检查 Diff 和定向测试后推送开发分支：

bash 复制代码

git push

如果发生冲突，先查看现场，不要推送：

bash 复制代码

git status
git diff --name-only --diff-filter=U

交给 AI 完整处理

推荐将冲突交给具备当前仓库访问权限的 AI 编码工具完整处理。AI 可以分析相关提交、修改冲突文件、检查残留标记并运行定向测试。

必须明确告诉 AI：

默认保留 main 已上线的全部有效功能。
同时保留当前开发分支中本次需求的全部有效功能。
不得为了消除冲突而简单选择一边、删除另一边或绕过测试。
如果两边修改的是同一个功能点，且业务方向互斥、无法同时保留，必须暂停并请人工确认，不能自行决定采用哪一边。

可直接使用 Main 冲突提示词。提示词允许 AI 完成代码修改和验证，但不允许 AI 在互斥业务方向之间擅自取舍。

冲突解决完成

AI 或开发者完成冲突处理后，确认没有未解决文件：

bash 复制代码

git status
git diff --name-only --diff-filter=U

暂存处理结果并检查：

bash 复制代码

git add <已解决的文件路径>
git diff --cached --check
git diff --cached

定向测试通过后提交并推送：

bash 复制代码

git commit -m "merge: 合入最新 main 并解决冲突"
git push

冲突解决后必须重新测试

将 main 合入开发分支并处理冲突后，准备上线的代码已经发生变化。之前的测试结果不能直接作为最终结果。

需要重新执行：

text 复制代码

开发分支 → develop → 测试环境

可通过 develop MR 或本地直接合并，具体步骤见 Develop 测试环境合并说明。

重新测试通过后，再回到"开发分支 → MR → main"的正式发布流程。

同一功能点方向互斥

如果 AI 判断两边对同一功能点的业务方向互斥、无法同时成立，应保持冲突现场并请需求负责人或相关代码负责人确认。人工确认方向后，再让 AI 继续完成修改和验证。

如果需要先恢复到合并前状态：

bash 复制代码

git merge --abort
git status

不要为了让 MR 变成"无冲突"而随意删除任一侧逻辑。

完整流程

text 复制代码

开发分支 → MR → main
                 │
                 └── 出现冲突
                        │
                        ▼
                  获取最新 main
                        │
                        ▼
                  main → 开发分支
                        │
                        ▼
              AI 保留两边功能并解决冲突
                        │
        同一功能点方向互斥时请人工确认
                        │
                        ▼
                 推送开发分支
                        │
                        ▼
              再合入 develop 重新测试
                        │
                   测试通过
                        │
                        ▼
                 完成 main MR

检查清单

当前操作方向是"最新 main → 开发分支"。
没有将 develop 合入开发分支。
main 已上线功能和当前需求功能都得到保留。
同一功能点存在互斥方向时已经完成人工确认。
git status 中没有未解决冲突。
Diff、CI、构建和定向测试均正常。
冲突解决后的代码已经重新合入 develop 测试。
正式发布仍然使用"开发分支 → MR → main"。