flutter-cherry-pick

Flutter Cherry-Pick ワークフロー

制約

このスキルには、次の厳格な制約があります。

• 対象リポジトリ： flutter/flutter リポジトリでのみ使用してください。
• 対象チャンネル： stable、beta、または flutter-<major>.<minor>-candidate.<hotfix>（例：flutter-3.10-candidate.0）の形式に一致するリリース候補ブランチを対象とする cherry-pick にのみ使用してください。
• PR のステータス： master にすでに正常にマージされているプルリクエストにのみ使用してください。

クイックスタート

マージ済みの PR 番号または URL を指定し、必要に応じて対象チャンネルを指定すると、このスキルを実行できます。

• 「PR 187045 を stable に cherry-pick」
• 「https://github.com/flutter/flutter/pull/186952 を beta に CP するよう依頼」
• 「PR 187045 を CP」（エージェントがチャンネルを確認します）

ワークフロー

フェーズ 1：初期化とチャンネルの検出

1. 入力を特定します：
   • 元の PR：<ORIGINAL_PR>（ユーザーが指定した番号または URL）。
   • 対象チャンネル：<CHANNEL>（stable または beta）。
2. チャンネルを判定します：
   • ユーザーのリクエストから対象チャンネルを解析します。
   • 必須確認ステップ： ユーザーのリクエストに対象チャンネルが指定されていない場合は、ツールの呼び出しを停止して、ユーザーに質問しなければなりません。「これを stable と beta のどちらに cherry-pick しますか？」と尋ね、回答を待ってから処理を続行してください。
3. flutter リポジトリのルートにいることを確認します。
4. 環境を確認します： リポジトリがクリーン（未コミットの変更がない状態）であることを確認します。git status --porcelain を実行して確認してください。保留中の変更がある場合は、処理を停止して、解決または stash するようユーザーに依頼してください。

フェーズ 2：Cherry-Pick オーケストレーターの実行

1. 補助スクリプトを実行して処理を開始します。

   <DART_EXECUTABLE> .agents/skills/flutter-cherry-pick/scripts/flutter_cp.dart --pr <ORIGINAL_PR> --channel <CHANNEL> --action start
   

2. スクリプトの出力を評価します：
   • 終了コード 0（成功）：
     • 出力の末尾は SUCCESS:AUTOMATED:<CP_PR> または SUCCESS:MANUAL:<CP_PR> になります。
     • <CP_PR> 番号を抽出します。
     • フェーズ 4：テンプレートの記入に進みます。
   • 終了コード 2（競合）：
     • cherry-pick で競合が発生し、スクリプトによってローカルブランチ cherry-pick-<ORIGINAL_PR>-to-<CHANNEL> に切り替わっています。
     • フェーズ 3：競合の解決に進みます。
   • 終了コード 1（エラー）：
     • 予期しないエラーが発生しました。失敗をユーザーに報告してください。

フェーズ 3：競合の解決

1. 競合を分析します：
   • スクリプトの出力から競合しているファイルを特定します（または git status --porcelain を実行して、未マージのファイルを確認します）。
2. 競合を記録します： 発生した競合とその解決方法を明確に記述します。この情報は最終的な PR の説明に含める必要があります。
3. 自動解決を試みます：
   • 競合している各ファイルについて、競合マーカー（<<<<<<<、=======、>>>>>>>）を分析します。
   • 競合が単純なもの（例：インポート順序、軽微な書式設定、変更箇所が重複しない場合）であれば、解決してください。
4. ユーザーへのフォールバック：
   • 競合を自動的に解決できない場合、または競合が Flutter ユーザーに影響するロジックの変更に関係する場合：
     • 競合しているファイルの一覧をチャットでユーザーに提示します。
     • エディターで解決するようユーザーに依頼します。
     • ツールの呼び出しを停止し、ユーザーが解決したことを確認するまで待ちます。
5. 処理を続行します：
   • すべての競合が解決したら（あなたまたはユーザーによる解決のいずれの場合も）、git add <resolved-files> を実行してステージングします。
   • オーケストレーターのスクリプトを再開します。

     <DART_EXECUTABLE> .agents/skills/flutter-cherry-pick/scripts/flutter_cp.dart --pr <ORIGINAL_PR> --channel <CHANNEL> --action continue
     

   • スクリプトが git cherry-pick --continue を実行し、push して PR を作成した後、SUCCESS:MANUAL:<CP_PR> を出力します。
   • <CP_PR> 番号を抽出し、フェーズ 4：テンプレートの記入に進みます。

フェーズ 4：テンプレートに記入して適用する

1. テンプレートを取得する：
   • ローカルの cherry-pick テンプレートを読み込みます（このスキルを基準にした相対パス [PULL_REQUEST_CP_TEMPLATE](../../../.github/PR_TEMPLATE/PULL_REQUEST_CP_TEMPLATE.md) にあります）。
2. コンテキストを収集する：
   • 元の PR の説明を解析し、リンクされた Issue（例：「Fixes #187322」、「Closes #123」）を確認します。
   • 見つかった場合は、Issue の詳細を取得します：gh issue view <ISSUE_NUMBER> --json title,body
   • 必要に応じて、元の PR の詳細を取得します。
   • フェーズ 3 で競合が発生して解決された場合は、その競合に関する記録を収集します。
3. テンプレートの草案を作成する：
   • Issue と元の PR のコンテキストに基づき、LLM の推論を用いて、取得したテンプレートの各項目に記入します。
   • 競合を解決した場合は、何をどのように解決したかを説明し、PR の説明（「Description」または「Changelog」セクションなど）に明記します。
   • テンプレートの Markdown 構造を維持します。
   • 重要： 各セクション内の説明文やガイドライン（例：「影響は何ですか……」など）は、回答に置き換える際に削除します。チェックボックスや選択肢に関する説明（例：「リスクレベルは何ですか……」、「自信はありますか……」など）は削除しないでください。
   • テキストセクションへの記入例（説明文を削除）：
     • 記入前：

       ### 影響
       この cherry-pick の影響は何ですか？（ユーザーへの影響を説明してください……）
       

     • 記入後：

       ### 影響
       破損した GIF をレンダリングする際に画像デコーダーで発生する重大なクラッシュを修正します。
       

   • チェックボックス／選択項目セクションへの記入例（選択肢は削除しない）：
     • 記入前：

       ### 共有エンジニアリングコホート
       エンジニアリングコホート（例：Flutter Tooling、Engine、Framework）に相談しましたか？
       - [ ] はい
       - [ ] いいえ
       

     • 記入後：

       ### 共有エンジニアリングコホート
       エンジニアリングコホート（例：Flutter Tooling、Engine、Framework）に相談しましたか？
       - [x] はい
       - [ ] いいえ
       

4. ユーザーと確認する（必須のゲートステップ）：
   • 記入したテンプレートをチャットでユーザーに提示し、承認または修正を依頼します。
   • ツールの呼び出しを必ず停止し、 ユーザーがチャットで明示的に承認するまで待ちます。事前にテンプレートを適用しないでください。
5. テンプレートを適用し、タイトルを更新してラベルを追加する：
   • ユーザーから明示的な承認を受けた後に限り、このステップに進みます。
   • PR のタイトルが [<CHANNEL>] <ORIGINAL_PR_TITLE> の形式になっていることを確認します。
   • cp: review ラベルが CP PR に追加されていることを確認します。
   • 承認されたら、CP PR の説明とタイトルを更新し、ラベルを追加します：

     gh pr edit <CP_PR> --title "[<CHANNEL>] <ORIGINAL_PR_TITLE>" --body "<FINAL_TEMPLATE>" --add-label "cp: review"
     

     （注：GraphQL の非推奨化エラーが原因で gh pr edit が失敗した場合は、gh api 経由で REST API を使用して本文を更新し、ラベルを追加できます。）
   • 新しい cherry-pick PR のリンクをユーザーに提示します。