docs: refine PR review and merge workflow
This commit is contained in:
Q3CC
+69
-32
@@ -26,6 +26,7 @@
|
||||
10. 默认不编译测试。处理完成后提醒用户自行测试。
|
||||
11. 任何 GitHub 评论、回复、感谢留言发出后，AI 都必须立即再读一遍线上实际内容，确认正文不是乱码、不是 `?`、不是编码异常；如果发现异常，必须立刻修正后再继续后续流程。
|
||||
12. 如果流程执行过程中，PR 的实时目标分支被别人改掉，或者不再是 `dev`，AI 必须停止当前合并流程，重新拉取信息后再决定下一步。
|
||||
13. 进入“阶段 2：分析与审查”时，AI 必须先给当前 PR 添加 `审查中` 标签，并在开始正式审查前确认该标签已经在线上生效。
|
||||
|
||||
## 输入要求
|
||||
|
||||
@@ -53,7 +54,7 @@ AI 必须先执行下面这些动作，不能跳步：
|
||||
2. 拉取 PR 元数据：
|
||||
|
||||
```powershell
|
||||
gh pr view <PR_NUMBER> --repo <OWNER/REPO> --json number,title,body,author,baseRefName,headRefName,headRepository,headRepositoryOwner,changedFiles,additions,deletions,commits,files,isDraft,mergeStateStatus,mergeable,state,url
|
||||
gh pr view <PR_NUMBER> --repo <OWNER/REPO> --json number,title,body,author,baseRefName,headRefName,headRepository,headRepositoryOwner,changedFiles,additions,deletions,commits,files,labels,isDraft,mergeStateStatus,mergeable,state,url
|
||||
```
|
||||
|
||||
3. 先根据实时 `baseRefName` 处理目标分支：
|
||||
@@ -107,27 +108,37 @@ git worktree add --detach $TempWorktree origin/pr-<PR_NUMBER>
|
||||
|
||||
AI 分析时，必须完整执行下面这些要求：
|
||||
|
||||
1. 不能只看 PR 描述，必须结合真实 diff 和仓库现有代码上下文一起分析。
|
||||
2. 如果阶段 1 发生过 `master -> dev` 自动转向，分析时只能基于转向后的最新 diff，不得继续引用转向前的 diff 结论。
|
||||
3. 对于高风险文件，必须继续读取改动函数周边逻辑，确认消息流、状态流、配置项、回调流程、页面跳转流程是否一致。
|
||||
4. 必须分析并输出：
|
||||
1. 审查一开始必须先执行：
|
||||
|
||||
```powershell
|
||||
gh pr edit <PR_NUMBER> --add-label "审查中" --repo <OWNER/REPO>
|
||||
```
|
||||
|
||||
补充要求：
|
||||
|
||||
- 打标后必须立刻重新读取一次实时 PR 元数据，确认 `labels` 中已经出现 `审查中`。
|
||||
- 如果仓库里没有 `审查中` 标签、当前账号无权限打标，或者命令执行失败，必须立刻告知用户，不能假装已经开始审查。
|
||||
2. 不能只看 PR 描述，必须结合真实 diff 和仓库现有代码上下文一起分析。
|
||||
3. 如果阶段 1 发生过 `master -> dev` 自动转向，分析时只能基于转向后的最新 diff，不得继续引用转向前的 diff 结论。
|
||||
4. 对于高风险文件，必须继续读取改动函数周边逻辑，确认消息流、状态流、配置项、回调流程、页面跳转流程是否一致。
|
||||
5. 必须分析并输出：
|
||||
- 这个 PR 改了什么
|
||||
- 这些改动是否合理
|
||||
- 是否存在 bug / 风险 / 逻辑冲突
|
||||
- PR 当前是否可直接合并，例如 `mergeable`、`mergeStateStatus`
|
||||
5. 如果发现问题，结论必须按严重级别排序，优先写真正会影响功能、合并或后续维护的问题。
|
||||
6. 如果没有发现明确问题，也要说明剩余风险，例如：
|
||||
6. 如果发现问题，结论必须按严重级别排序，优先写真正会影响功能、合并或后续维护的问题。
|
||||
7. 如果没有发现明确问题，也要说明剩余风险，例如：
|
||||
- 未运行测试
|
||||
- 需要人工验证真实业务接口
|
||||
- 当前仅完成静态分析
|
||||
7. 在准备进入后续合并步骤前，必须再拉取一次实时 PR 元数据，确认：
|
||||
8. 在准备进入后续合并步骤前，必须再拉取一次实时 PR 元数据，确认：
|
||||
- PR 仍然是打开状态
|
||||
- PR 不是 draft
|
||||
- `baseRefName` 仍然是 `dev`
|
||||
|
||||
## 分析后评论规则
|
||||
|
||||
### 有问题时
|
||||
### 有问题 / 审核不通过时
|
||||
|
||||
如果发现需要作者或维护者注意的问题，AI 必须自动发 PR 评论，并且评论格式必须固定如下：
|
||||
|
||||
@@ -144,6 +155,10 @@ AI 分析时，必须完整执行下面这些要求：
|
||||
3. 正文内容要直接写问题，不要再套娃解释“下面是分析结果”。
|
||||
4. 评论内容必须基于实际检查到的问题，不能编。
|
||||
5. 评论发出后，必须立刻回读该评论的线上正文，确认不是乱码；如果有乱码，必须先修正评论，再继续后续动作。
|
||||
6. 如果问题能够明确定位到某个改动文件、代码块或行号，AI 应优先在对应文件的代码 diff / 代码附件上追加行级评论，直接指出问题和期望修改方式。
|
||||
7. 如果结论是“当前不能通过审查”，AI 必须明确写出“需要修改后再继续”，不能只写模糊提醒。
|
||||
8. 如果当前环境支持正式 PR review，且问题足以阻止合并，优先使用带“要求更改（Request changes）”语义的审查，而不是只留普通闲聊式评论。
|
||||
9. 行级评论是对总评论的补充，不得用零散行级评论替代总评论结论。
|
||||
|
||||
### 没问题时
|
||||
|
||||
@@ -158,49 +173,52 @@ AI 分析时，必须完整执行下面这些要求：
|
||||
如果 PR 有问题，但用户明确要求：
|
||||
|
||||
- 不等待 PR 作者修复
|
||||
- 由当前 AI 直接本地处理冲突和问题
|
||||
- 由当前 AI 直接修改 PR 分支代码，处理冲突和问题
|
||||
- 处理完成后继续合并
|
||||
|
||||
则必须进入下面的流程。
|
||||
|
||||
### 阶段 3：临时工作区合并
|
||||
### 阶段 3：临时工作区修复 PR 分支
|
||||
|
||||
禁止在用户当前工作区直接乱合并。
|
||||
|
||||
必须先创建临时 `worktree`，再在临时目录内处理：
|
||||
必须先创建临时 `worktree`，再在临时目录内处理 PR 分支：
|
||||
|
||||
```powershell
|
||||
git fetch origin dev
|
||||
git fetch origin pull/<PR_NUMBER>/head:refs/remotes/origin/pr-<PR_NUMBER>
|
||||
git worktree add <TEMP_WORKTREE> -b pr-<PR_NUMBER>-merge origin/dev
|
||||
git worktree add <TEMP_WORKTREE> -b pr-<PR_NUMBER>-fix origin/pr-<PR_NUMBER>
|
||||
```
|
||||
|
||||
进入临时目录后再执行：
|
||||
进入临时目录后，先把最新 `dev` 合到 PR 分支里，显式暴露冲突：
|
||||
|
||||
```powershell
|
||||
git merge --no-ff --no-commit origin/pr-<PR_NUMBER>
|
||||
git merge --no-ff --no-commit origin/dev
|
||||
```
|
||||
|
||||
处理规则：
|
||||
|
||||
1. 如果阶段 1 发生过 `master -> dev` 自动转向，本阶段必须以 `dev` 为唯一合并基准，不允许再回到 `master` 做本地吸收。
|
||||
2. 如果出现冲突，先解决冲突，再继续检查相关联逻辑。
|
||||
2. 如果出现冲突，先在 PR 分支上解决冲突，再继续检查相关联逻辑。
|
||||
3. 不能只消掉冲突标记就结束，必须继续看是否有设计冲突、状态字段不一致、调用链断裂、配置项名不一致、回调逻辑互相打架的问题。
|
||||
4. 如果 PR 本身逻辑有 bug，而用户又明确要求继续合并，AI 需要直接在本地修正。
|
||||
5. 修正时要清理无用旧代码，避免留下史山。
|
||||
6. 如果改了 SQL，按仓库规则同步本地 MySQL `xzs`。
|
||||
4. 如果 PR 本身逻辑有 bug，而用户又明确要求继续合并，AI 需要直接修改 PR 分支代码并修正。
|
||||
5. 修正完成后，必须把修改提交回 PR 分支并推送到远端；如果没有权限推送到 PR 来源分支，必须立刻停止并明确告知用户，不能假装 PR 已修好。
|
||||
6. 推送完成后，必须重新拉取一次实时 PR 元数据与最新 diff，确认线上 PR 已包含本次修复，再决定是否继续合并。
|
||||
7. 修正时要清理无用旧代码，避免留下史山。
|
||||
8. 如果改了 SQL，按仓库规则同步本地 MySQL `xzs`。
|
||||
|
||||
### 阶段 4：本地修复后的自检清单
|
||||
### 阶段 4：PR 修复推送后的自检清单
|
||||
|
||||
完成临时合并与本地修复后，必须自检下面这些项目：
|
||||
完成 PR 分支修复并推送后，必须自检下面这些项目：
|
||||
|
||||
1. `git status` 中不能再有未处理冲突。
|
||||
2. 相关文件中不能残留冲突标记。
|
||||
3. 新旧逻辑之间不能出现字段名、消息名、步骤编号、状态名不一致。
|
||||
4. 需要检查与本次功能直接相关的上下游代码，不能只改当前冲突文件。
|
||||
5. 要重新查看最终 diff，确认本地修复没有引入明显回归。
|
||||
5. 要重新查看最终线上 diff，确认修复后的 PR 没有引入明显回归。
|
||||
6. 要重新拉取一次实时 PR 元数据，确认该 PR 的 `baseRefName` 仍然是 `dev`；如果不是，停止后续合并并先反馈用户。
|
||||
7. 默认不编译测试，最后提醒用户自行测试。
|
||||
7. 要确认 PR 当前已经回到可继续处理的状态，例如不再是 `draft`，且 `mergeable` / `mergeStateStatus` 没有出现新的阻塞。
|
||||
8. 默认不编译测试，最后提醒用户自行测试。
|
||||
|
||||
## 合并提交信息规则
|
||||
|
||||
@@ -212,6 +230,8 @@ git merge --no-ff --no-commit origin/pr-<PR_NUMBER>
|
||||
|
||||
必须重新分析“最终合并结果到底做了什么”，然后重写提交信息。
|
||||
|
||||
这些规则同样适用于最终执行 `gh pr merge` 时使用的标题与正文。
|
||||
|
||||
### 提交信息要求
|
||||
|
||||
1. 标题必须描述最终落地功能，不是描述 Git 动作。
|
||||
@@ -243,9 +263,23 @@ feat: support SUB2API mode for OAuth generation and callback handling
|
||||
|
||||
## 最终合并与收尾
|
||||
|
||||
如果本地已经解决该 PR 的内容，并且最终代码已经进入 `dev` 分支，则继续执行下面动作。
|
||||
如果 PR 分支上的冲突 / 问题已经修好，并且复检确认该 PR 可以继续合并到 `dev`，则继续执行下面动作。
|
||||
|
||||
### 1. 感谢作者
|
||||
### 1. 合并 PR
|
||||
|
||||
优先直接合并这个 PR，而不是只在本地偷偷吸收代码后手工关闭：
|
||||
|
||||
```powershell
|
||||
gh pr merge <PR_NUMBER> --merge --subject "<TITLE>" --body "<BODY>" --repo <OWNER/REPO>
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
1. `--subject` 与 `--body` 必须遵守上面的“合并提交信息规则”。
|
||||
2. 合并前必须再次确认 PR 仍然是打开状态、目标分支仍然是 `dev`、线上 diff 已包含你刚刚推送的修复。
|
||||
3. 如果合并时发现新的冲突、状态检查阻塞或权限问题，必须停止并把真实阻塞原因反馈给用户。
|
||||
|
||||
### 2. 感谢作者
|
||||
|
||||
此时需要自动给 PR 留一条感谢评论。
|
||||
|
||||
@@ -263,7 +297,7 @@ feat: support SUB2API mode for OAuth generation and callback handling
|
||||
感谢贡献这次改动，核心思路和主体实现已经吸收进 dev 分支了。我这边补了一下合并过程里的冲突和相关修正，后续如果你还有类似改进也欢迎继续提交。
|
||||
```
|
||||
|
||||
### 2. 自动关闭 PR
|
||||
### 3. 自动关闭 PR
|
||||
|
||||
如果 PR 还没有因为合并而自动关闭，则感谢评论发完后，自动关闭该 PR：
|
||||
|
||||
@@ -273,7 +307,7 @@ gh pr close <PR_NUMBER> --repo <OWNER/REPO>
|
||||
|
||||
如果需要，先评论再关闭，不要把感谢遗漏掉。
|
||||
|
||||
### 3. 评论编码复检
|
||||
### 4. 评论编码复检
|
||||
|
||||
无论是问题评论、感谢评论，还是其他直接发到 GitHub 的回复，只要消息已经发出，AI 必须执行一次“发送后复检”：
|
||||
|
||||
@@ -291,11 +325,14 @@ AI 在对当前用户做最终反馈时，至少要说明：
|
||||
3. 是否已经执行 `master -> dev` 自动转向
|
||||
4. 是否发现重复的 `dev` PR
|
||||
5. 是否发现问题
|
||||
6. 是否已经发了 PR 评论
|
||||
7. 是否已经本地合并并修复
|
||||
8. 是否已经关闭 PR
|
||||
9. 如果改了代码但没跑测试，要明确提醒用户测试
|
||||
6. 是否已经给 PR 添加 `审查中` 标签
|
||||
7. 是否已经发了 PR 评论 / 行级代码评论
|
||||
8. 是否已经要求 PR 修改后再继续
|
||||
9. 是否已经修改 PR 分支并推回远端
|
||||
10. 是否已经完成 PR 合并
|
||||
11. 是否已经关闭 PR
|
||||
12. 如果改了代码但没跑测试，要明确提醒用户测试
|
||||
|
||||
## 给 AI 的一句话执行要求
|
||||
|
||||
拿到本文件后，AI 必须按“先真实读取 PR 元数据，先校正目标分支，再拉取最新 diff 做分析，再按用户要求决定是否进入临时合并修复，最后重写提交信息并在完成后感谢作者、关闭 PR”的顺序执行，不能跳步，不能猜，不能偷懒。
|
||||
拿到本文件后，AI 必须按“先真实读取 PR 元数据，先校正目标分支，再拉取最新 diff，在正式审查开始时先给 PR 打上 `审查中` 标签并确认已生效；如果审核不通过，就在对应代码附件上评论并明确要求更改；如果用户要求继续处理冲突和问题，就先修好并推回 PR 分支，再按规则合并 PR，最后感谢作者、关闭 PR”的顺序执行，不能跳步，不能猜，不能偷懒。
|
||||
|
||||
Reference in New Issue
Block a user