shepherd-prs

PR 跟进技能（flutter/flutter）

此技能定义了使用原生 GitHub CLI（gh）命令跟进 flutter/flutter 仓库中拉取请求的规范操作手册。

1. 检查 PR 状态

当用户询问开放或已批准的 PR 状态时：

1. 列出你自己的开放 PR：

   gh pr list --repo flutter/flutter --author <username> --state open --json number,title,url,mergeable,reviewDecision
   

2. 列出正在跟进／已评审的第三方 PR：

   gh pr list --repo flutter/flutter --search "reviewed-by:<username> -author:<username> is:open" --json number,title,url,mergeable,reviewDecision
   

3. 检查 PR 的详细检查结果：

   gh pr checks <number> --repo flutter/flutter
   

4. 检查评审、标签和评论：

   gh pr view <number> --repo flutter/flutter --json labels,reviewDecision,reviews,comments
   

2. 自动提交前的验证规则

在应用或重新应用 autosubmit 标签（gh pr edit <number> --repo flutter/flutter --add-label autosubmit）之前，务必执行以下预检，以确保 autosubmit 机器人不会拒绝或移除该标签：

1. 在评论中检查此前移除 autosubmit 的记录：

   • 务必检查 PR 评论，确认 autosubmit 标签此前是否被 auto-submit 机器人移除：

     gh pr view <number> --repo flutter/flutter --json comments
     

   • 查找来自 auto-submit 的消息，例如 "autosubmit label was removed..."。
   • 如果此前移除过该标签，请确认机器人给出的具体原因（例如 CI 检查失败、批准数不足、合并冲突或分支过期），并在重新应用 autosubmit 前确认相关问题已解决。

2. 确认基准提交是否过期（超过 7 天）：

   • 检查 PR 的基准提交是否过期（超过 7 天）。
   • 如果基准提交超过 7 天，在尝试添加 autosubmit 前，务必指示用户更新分支或执行分支更新：

     gh pr update-branch <number> --repo flutter/flutter
     

   • 在分支更新完成且更新后分支上的 CI 检查通过之前，不要应用 autosubmit。

3. 严格确认所需的评审者批准数：

   • 在添加 autosubmit 前，严格确认第三方贡献者 PR（CONTRIBUTOR、FIRST_TIME_CONTRIBUTOR、NONE）至少获得 2 位团队成员（MEMBER 或 OWNER）的批准，以免机器人再次移除该标签。
   • 检查 gh pr view <number> --repo flutter/flutter --json reviews 中的 reviews，确认 Flutter 团队成员的批准数。

4. 确认所有状态检查均 100% 通过：

   • 任何 CI 检查失败时，Flutter 的 autosubmit 机器人都会自动移除 autosubmit 标签。
   • 确认所有状态检查均已通过（SUCCESS/pass）。
   • 如果任何检查不稳定、失败或正在等待重试：
     1. 不要立即应用 autosubmit 标签。
     2. 告知用户失败的检查，并让其先重试。
     3. 只有在所有重试的检查均成功完成后，才应用 autosubmit 标签：

        gh pr edit <number> --repo flutter/flutter --add-label autosubmit
        

3. 第三方贡献者 PR（要求 2 位评审者）

• 第三方贡献者（CONTRIBUTOR、FIRST_TIME_CONTRIBUTOR、NONE）创建的拉取请求，需要先获得 Flutter 团队成员（MEMBER 或 OWNER）的 2 项明确批准，autosubmit 机器人才能合并。
• 如果第三方 PR 仅获得一位团队成员批准，却已应用 autosubmit 标签，机器人会移除该标签。
• 操作：通过 gh pr view <number> --repo flutter/flutter --json reviews 严格确认至少有 2 位团队成员批准后，再添加 autosubmit，以免机器人再次移除该标签。如果只有 1 项批准，请提醒用户在应用该标签前请求第二位评审者。

4. 检查失败与手动重新运行 LUCI

• 由于 GitHub App 权限策略，无法通过 GitHub API 重新运行第三方检查（例如由 flutter-dashboard 创建的 LUCI 检查）。
• 操作：
  1. 输出失败检查对应的确切 LUCI Buildbucket 链接（例如 https://cr-buildbucket.appspot.com/build/<build_id>）。
  2. 指示用户打开该 URL，并在 LUCI 页面上点击 Retry Build。
  3. 如果手动重试后检查仍然失败，请检查失败日志（gh pr view <number> --repo flutter/flutter 或 flutter-pr-checks-finder），并向用户总结失败原因。

5. 过期分支更新、CICD 标签与令牌权限范围

• 如果 PR 分支未与 master 保持同步（包括基准提交超过 7 天的情况）：
  • 在尝试添加 autosubmit 之前，务必使用 gh pr update-branch <number> --repo flutter/flutter 更新分支。
• 重新添加 CICD 标签：
  • 使用 gh pr update-branch 更新分支后（或在协助处理尚未运行 CI 的 PR 时），CICD 标签通常会被移除，或者需要该标签才能在更新后的提交上启动 CI 检查。
  • 分支更新后，务必检查是否存在 CICD 标签；如果缺失，则重新添加：

    gh pr edit <number> --repo flutter/flutter --add-label CICD
    

• 令牌权限范围过期错误：如果因工作流文件权限而导致更新失败（ERROR: ... lacks the "workflow" scope），请指示用户刷新 CLI 权限范围：

  gh auth refresh -h github.com -s workflow
  

6. 目标分支修正与合并冲突

• 已撤销审核警告：更改 PR 的目标分支通常会导致 GitHub 自动撤销现有批准。如果目标分支已更改，请提醒用户，以便他们在 GitHub 上重新批准。
• 合并冲突：如果 PR 存在冲突（MERGEABLE 为 CONFLICTING），请通知用户，以便作者解决冲突。