shepherd-prs

Pull Request の進行管理スキル（flutter/flutter）

このスキルでは、ネイティブの GitHub CLI（gh）コマンドを使用して、flutter/flutter リポジトリの pull request を進行管理するための標準的な手順を定義します。

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 のコメントを確認し、auto-submit ボットによって autosubmit ラベルが過去に削除されたことがあるか、必ず確認してください：

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

   • "autosubmit label was removed..." などの、auto-submit からのメッセージを探してください。
   • ラベルが過去に削除されていた場合は、ボットが示した正確な理由（CI チェックの失敗、承認不足、マージの競合、ブランチの古さなど）を特定し、autosubmit を再付与する前に根本的な問題が解決されていることを確認してください。

2. ベースコミットが最新か確認する（7 日超経過している場合）：

   • PR のベースコミットが古くなっていないか（7 日超経過しているか）確認してください。
   • ベースコミットが 7 日を超えて古い場合は、autosubmit の追加を試みる前に、必ずブランチの更新を実行するよう指示するか、実行してください：

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

   • ブランチの更新が完了し、更新後のブランチで CI チェックが成功するまで、autosubmit を付与しないでください。

3. 必要なレビュアーの承認を厳密に確認する：

   • サードパーティーのコントリビューターの PR（CONTRIBUTOR、FIRST_TIME_CONTRIBUTOR、NONE）には、autosubmit を追加する前にチームメンバー（MEMBER または OWNER）による少なくとも 2 件の承認があることを厳密に確認してください。これにより、ボットがラベルを再び削除するのを防ぎます。
   • gh pr view <number> --repo flutter/flutter --json reviews の reviews を確認し、Flutter チームメンバーからの承認数を確かめてください。

4. すべてのステータスチェックが 100％ 成功していることを確認する：

   • Flutter の autosubmit ボットは、CI チェックが 1 つでも失敗すると 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）が作成した pull request は、autosubmit ボットがマージする前に、Flutter チームメンバー（MEMBER または OWNER）からの明示的な承認が 2 件必要です。
• サードパーティーの PR にチームメンバー 1 名だけが承認している状態で autosubmit ラベルを付与すると、autosubmit ボットはラベルを削除します。
• 対応：autosubmit を追加する前に、gh pr view <number> --repo flutter/flutter --json reviews でチームメンバーからの承認が少なくとも 2 件あることを厳密に確認し、ボットがラベルを再び削除するのを防いでください。承認が 1 件しかない場合は、ラベルを付与する前に 2 人目のレビュアーにレビューを依頼するよう、ユーザーに伝えてください。

4. チェックの失敗と LUCI の手動再実行

• GitHub App の権限ポリシーにより、flutter-dashboard が作成した LUCI チェックなどのサードパーティのチェック実行は、GitHub API 経由で再実行できません。
• 対応：
  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 の対応中）は、更新後のコミットで CI チェックを開始するために、CICD ラベルが削除されているか、ラベルの追加が必要になることがよくあります。
  • ブランチ更新後は必ず 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）、作成者が解決できるようユーザーに知らせます。