レビュアープレイブック

PRのレビューとイシューのトリアージを行うための運用モデル。大量の処理量でもレビューの品質を高く保つために設計されており、リスクに基づいてルーティングされるため、重大な変更には必要な注意が払われ、小さな変更がすべて同じゲートを通る必要がありません。

実際のフェッチシーケンスやレビューの判断に関する詳細は、PRレビュープロトコルをご覧ください。このページは_運用モデル_であり、プロトコルは_手順_です。

高速パス

このセクションを使用して、より深く読む前にレビューをルーティングします。各行は、詳細を説明するセクションへのリンクです。

ルーティングの期待値についてはPRレーンを使用し、レビューの深さについてはこのプレイブックのリスクマトリクスを使用してください。

レビュー深度行列

domain:security は risk:* とは引き続き独立しています。変更されたコンポーネントがセキュリティ関連に見えるというだけでなく、実効的なセキュリティ境界または信頼境界に対して使用してください。いずれのラベルでも、同じ詳細レビューと、独立した 2 名の Core による承認プロセスが開始されます。自動レビューは Core Team の承認としてカウントされません。

判断に迷う場合は上位に分類し、マージ前にメンテナーに境界を解決してもらってください。

リスクラベルは現在手動です。#9345 により、将来のリスク分類器は、メンテナーが別途変更を有効化するまで、レポートのみの状態に維持されます。labels automation contract に従ってください。risk:manual は、メンテナーによる修正を維持すべき場合に自動的なリスク置換を停止しますが、レビューまたは承認の要件を軽減することは決してありません。

ラベルはメンテナー用のメタデータです。正しいラベルが明白で、かつ権限がある場合は、レビューを確定する前に自分で修正してください。作成者に確認するのは、適切なラベルの選択が曖昧な場合、またはラベル権限を持つ人が誰もいない場合に限ります。

標準的なワークフロー

5分間のインテーク

新しいPRごとに、コードを読む前に:

1. PRテンプレートが完了していることを確認してください：概要、検証証拠、セキュリティとプライバシー、互換性、ロールバック（中/高の場合）。
2. ラベルが存在し、妥当であることを確認します: size:*、risk:*、スコープラベル、該当する場合はコントリビューターのティア。
3. CI Required Gate シグナルのステータスを確認します。
4. スコープの確定は重要な懸念事項です。明確な理由がない限り、複数の機能を含む巨大なPRは分割して提出する必要があります。
5. プライバシー/データ管理ルールを確認してください。完全なルールについてはプライバシーをご覧ください。
6. PRで視覚的な表示が変更される場合は、作成者が実際にサポートされているインターフェースを使用して確認し、代表的なサイズのプライバシーに配慮したスクリーンショットを提供したことを確認してください。スモークテストを実施しなかったという記述は、その不足を記録するものではありますが、要件を満たすものではありません。

受け入れチェックのいずれかに失敗した場合は、実行可能なチェックリストのコメントを1つ残して停止してください。受け入れを通過していないPRを詳細にレビューしないでください。差分について検討した後よりも、このレイヤーでのやり取りの方がコストが低くなります。

高速レーチェックリスト（すべてのPRに対して）

• スコープの境界は明確で信頼性があります。
• 動作の変更は、制御する契約と照合されます: アーキテクチャドキュメント、ソース・オブ・トゥルースモジュール、トレイト境界、既存のテスト、公開APIの形状、ソースコメント、またはメンテナの明示的な決定。
• PR本文の来歴は true です。引用された RFC、監査、issue、PR、パス、生成されたアーティファクト、またはフォローアップの発見が存在し、主張を裏付けています。
• 検証エビデンスには、依拠しているチェックの名称と、それらが変更後の動作をどのようにカバーするかを記載します。
• ユーザーが直接観測できる主張は、ユーザー境界を特定し、そこに到達する最小限の信頼できる証拠を提供します。単体テスト、モック、コンパイル、または一般的なCIの証拠では不十分な場合は、ユーザー境界の証明を使用してください。
• 視覚的な表示変更では、特定可能なリビジョンにおける実際のインターフェースの証拠と、結果を評価できるだけの周辺レイアウトを含むスクリーンショットを提示します。文字列アサーション、コンポーネントのみのスナップショット、ヘルパーレベルのレンダラーテストでは、この証拠の代わりにはなりません。インタラクションや遷移に関する主張では、ユーザーの操作と観測された結果も明記します。
• 最新の必須 CI が同じ head、target、および feature set をカバーしている場合、重複したローカルの Cargo は不要です。追加の検証を求めるのは、必須ゲート内の名前付きギャップに対応する場合のみにしてください。たとえば macOS/Windows テスト、クロスプラットフォームの Clippy、デスクトップカバレッジ、リリースターゲットビルド、古い CI、または利用不可の CI などです。
• ユーザーが直面する動作の変更は文書化されています。
• 著者は、行動と影響範囲（特にAI支援のPRの場合）を理解していることを示しています。
• ロールバックの手順は具体的ですが、「元に戻す」は具体的ではありません。
• 互換性とマイグレーションの影響は明確です。
• MSRV、ピン留めされたツールチェーン、またはその他のバージョン下限の変更は、互換性に影響するものとして明記されます。PR では誰がアップグレードする必要があるかを説明し、CI とインストーラーのベースラインが一致し、ソースビルドユーザーに影響し得る変更の場合はリリースノートで新しい下限が記載されます。
• 差分アーティファクトに個人データや機密データが漏洩しておらず、テストでは中立でプロジェクト固有のプレースホルダーが使用されています。
• 命名とアーキテクチャ境界はプロジェクトの契約（AGENTS.md、アーキテクチャ概要）に従います。

ドリフトサーフェスのレビュー

新たに重複する解釈用サーフェスは、レビュー上のリスクとして扱います。PR では、コード、スキーマ、テスト、WIT、設定、またはランタイムディスパッチがすでに管理している動作を再記述するコメント、例、生成されたスナップショット、マッピングテーブル、設定ミラー、または並列レジストリを追加してはなりません。ただし、その新しいサーフェスがその所有元から機械的に導出されるか、明確にそこを参照している場合を除きます。

新しい記述面が乖離する可能性があり、将来の読者、レビュー担当者、または自動化がそれをソースよりも権威あるものとして扱ってしまうおそれがある場合は、ブロックするか変更をリクエストしてください。一般的な例としては、コードで強制されていない動作を説明するコメント、enum やスキーマのリストを手作業で重複させたドキュメント、ユーザーが観測できる動作ではなく実装の詳細をスナップショットするテスト、別のモジュールがすでに所有しているキー空間をコピーするレジストリなどがあります。

これらの解決策のいずれかを優先してください:

• 重複するサーフェスを削除し、正規の所有者を読みやすくします。
• 正規の所有者からセカンダリサーフェスを生成します。
• 再記述を、ソースへのポインターと、そのポインターがそこにあるべき理由に置き換えてください。

whyコメントは、型システムやテストでは表現できない、自明でない不変条件、危険性、トレードオフを示す場合には、引き続き歓迎されます。コメントでは意図を説明し、近くの制御フローを言い換えたり、第二の契約になったりしないようにしてください。

共有キー空間向けの型付きディスパッチ

wire メソッド名、コンパイル済みチャネル型キー、プロバイダースロット、フロントエンド/バックエンドのレジストリキーなどの共有キー空間では、API または設定の境界で生の文字列を解決することで、このルールを適用してください。下流コードでは、enum、マクロ生成テーブル、trait/ファクトリーレジストリ、またはその他の正規の管理元を介してディスパッチしてください。並列の文字列 match アーム、手書きのディスパッチテーブル、またはレビュー担当者の記憶に頼って同期を維持する必要がある重複リストを追加しないでください。

これはAPI境界での文字列定数を禁止するものではありません。新しいバリアントを追加した際に、あるコンシューマーを暗黙的にスキップしたままコンパイルが通ってしまうような、第2のディスパッチ面を防ぐものです。良い例としては、ワイヤーメソッド名のためのRPC Method レジストリや、チャンネルコンパイルキーのための CHANNEL_COMPILE_SPECS があり、これらでは唯一の正規オーナーが下流のカバレッジを駆動します。

高リスク対象のデープレビュー チェックリスト

risk:high または domain:security を付けた PR では、各カテゴリについて具体的な例を 1 つ確認してください。具体的な事例 1 つのほうが、一般的な主張 5 つより有効です。

• セキュリティの境界: デフォルトで拒否する動作が維持され、意図しないスコープの拡大を防ぎます。
• 障害モード: エラー処理が明示的であり、安全に劣化します。
• 契約の安定性: CLI、設定、またはAPIの互換性が維持されているか、移行が文書化されている。
• Diff shape: 大規模または新規統合の PR は一貫性があり、現時点でマージが正当化され、容易に分割できず、大部分が重複した機構ではない。
• 生成されたアーティファクト: ポリシー、スキーマ、ルート、マイグレーション、ロックファイル、リリースアーティファクト、ケイパビリティ、パッケージ、ランタイムの動作、またはレビュアーの証拠に影響する生成ファイルは、ソースと同様にレビューされます。
• ツールチェーン互換性: MSRV または pinned-toolchain の変更は意図的であり、CI/Docker/インストールの各サーフェスで整合し、ダウンストリーム/ソースビルドユーザー向けに文書化されています。
• 観測可能性: シークレットを漏洩させることなく障害を診断可能。
• ロールバックの安全性: 影響範囲と被害の拡大が明確。

コメントの形状

チェックリスト形式のコメントを推奨し、1つの明確な結果を指定してください：

• マージの準備ができました (理由を記載してください)。
• 著者のアクションが必要 (順序付きブロックリスト)。
• セキュリティまたはランタイムのより深いレビューが必要 (具体的なリスクと要求された証拠を記載してください)。

曖昧なコメントは避けられるやり直しを生み出します。「これは問題かもしれない」と書きたくなったら、さらに30秒かけて具体的なシナリオに書き換えるか、コメントを削除してください。

イシューの分類

同じリスクルーティングの原則がイシューにも適用されますが、ラベルとシグナルは異なります。

Issue の risk:* ラベルは、レポートから想定される修正の影響範囲を表します。PR の risk:* ラベルは、レビュー対象の実際の差分を表します。Issue が PR になる際は、Issue のラベルを自動的に引き継ぐのではなく、リスクを再評価してください。

トリアージラベル

Assignee はアクティブな作業を意味します。ルーティングの証跡は、なぜ issue が特別な stale 保護、トラッカーでの扱い、または保留中のメンテナー判断を必要とするのかを記録します。status:blocked は、別途 status:no-stale 保護も必要とする場合を除き、記録された未解決のブロッカーのみを必要とします。Project board contract は、受け入れられる証跡のソースとルーティングの結果を定義します。ラベルは該当しそうな領域を特定できますが、ラベルだけでは所有権や stale 保護にはなりません。

解像度ラベル

解決ラベルは、アイテムをクローズするかアクティブキューから削除する場合にのみ使用してください。これらは最終的な結果を説明するものであり、オープンのままにすべき作業の status:* ライフサイクルラベルを置き換えるものではありません。ラベルガイドが、現在の解決ラベルの定義および移行の保留に関する信頼できる情報源です。

重複の場合は、議論を終了またはリダイレクトする前に正規のターゲットへリンクしてください。無効なレポートの場合は、そのレポートが対応不可である理由、または代わりにどこへ送るべきかを説明してください。明示的に取り組まないと決めた作業については、ボードレベルの Won't Do / ライブの wontfix パスを使用し、簡潔な理由を残してください。

置き換えられた PR や issue のパスについては、Superseding PRs を使用し、関連する場合は貢献者のクレジットを保持してください。

レポート内のログやペイロードに個人識別子や機密データが含まれている場合は、より詳細な調査を行う前に削除を依頼してください。調査プロセスでは、その露出が拡大しないようにする必要があります。

ディスカッションの管理

Discussions は、steward もしくはレビューの定期サイクルが存在する場合にのみ、維持されたコミュニティの場となります。デフォルトのサイクルは、新規および最近アクティブなスレッドに対する週次のメンテナーによる確認です。指名された steward がその場の確認を担当することもありますが、steward が維持するのはあくまでその場であり、そこに現れるすべての質問、アイデア、実装の所有者になるわけではありません。

ディスカッションの各パスでは、以下を実行します。

1. カテゴリの適合性、未回答のQ&A、スパム、機密データ、および具体的なプロジェクト成果を生み出したスレッドについて、新規および最近アクティブなスレッドを確認します。
2. まだ検討段階のものや、Discussions 内で回答できるもの、あるいはショーケース・デモ・投票・お知らせ・幅広いフィードバックを集めるスレッドとして役立つものなど、軽量なコミュニティ向けの会話は Discussions に残しておきましょう。
3. 具体的な成果を、それを管理する適切な場所に反映してください。バグや承認された機能スコープは issue へ、アーキテクチャの提案は RFC issue へ、PR 固有の詳細は PR コメントへ、恒久的な運用ルールは maintainer または contributor 向けドキュメントへ反映します。
4. 発端となった Discussion で、結果を引き継ぐ issue、RFC、PR、または doc への短い要約とリンクを添えてループを閉じます。カテゴリーと結果がそれを正確に反映する場合にのみ、回答としてマークしてください。
5. セキュリティに関わるスレッドは Security issues のプライベートな脆弱性報告パスにリダイレクトし、機密データは Privacy に従って取り扱い、純粋な宣伝やプロジェクトに関係のないスレッドはクローズしてください。プロジェクトに関連する有用なデモやインテグレーションは、メンテナーに作業の追跡を求めるものでない場合、コミュニティのショーケース素材として残してください。

ディスカッションが文書化された頻度でレビューされていない場合は、それを必須の受付経路として提示しないでください。スチュワードまたはレビュー頻度が回復されるまでは、受動的なアーカイブとして扱ってください。

PRバックログの整理

次のレビュー パスを選択する際は、レポート専用のキュー スナップショットを使用します:

python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table

このコマンドは、現在の GitHub の状態をオンデマンドで確認するためのものであり、永続的なキューでも、マージ権限の根拠でもありません。この all スナップショットは共通レーンをそれぞれ独立して実行するため、1 件の PR が複数のレーンに表示されることがあります。mine を含めるには --author LOGIN を追加します。GitHub 検索のステータスが成功している、メンテナーによって振り分けられた PR から開始するには --queue near-ready を使用します。これによりマージに近い可能性のある候補を優先しますが、マージ可能であることや、十分な承認を得ていることを意味するものではありません。確認や後続のレポートには --format json を使用し、GitHub 検索リンクには --format links を使用します。GitHub 検索が候補リストを提供し、スクリプトはタイムラインを作成者の対応からの経過時間の確認にのみ使用し、レビューは current-head の second-Core ルーティングにのみ使用します。不足している、または曖昧な詳細は不明のままです。実際のレビュー時に、マージ可能性、チェック、および承認の適用可否を確認してください。Depends on #... の親を子より先に優先してレビューします。親をレビューできない場合は、範囲を限定した独立した部分を早期にレビューするメリットがある場合を除き、子の詳細レビューを延期します。その後、親がマージされたら、子を更新して再検証します。Stacked PR は別のレポートレーンのままであり、古いというだけでレビュー可能になるわけではありません。

レビュー需要がキャパシティを超えた場合：

1. アクティブなバグおよびセキュリティPR（size:XS または size:S）をキューの先頭に保つ。
2. 重複する PR には統合を依頼し、作成者の了承を得たうえで、置き換え (superseded または replaced) を理由として古いものをクローズします。属性のルールについては Superseding PRs を参照してください。
3. 以下の PR の stale 化の段階を使用してください。PR バックログの整理では needs-author-action と stale-candidate を使用し、issue の stale スイープでは、正式な issue stale ポリシー に従って status:stale を使用します。

メンテナーが変更要求のレビューを送信し、次のステップがPR作成者に委ねられている場合は、同じレビュー/ラベルパケット内で needs-author-action を適用します。要求された変更がメンテナーによって修正可能で、メンテナーがクリーンアップをプッシュする意図がある場合、別のメンテナーまたはオーナーがブランチを引き継ぐ場合、あるいはブロックが作成者の作業ではなくメンテナーの判断を待っている場合には、これを追加しないでください。

根底にあるバグや機能が依然として有効な場合は、そのアイデアが却下されたと示唆するのではなく、イシュー、トラッカー行、代替 PR、または引き継ぎ計画にそれを保持してください。stale-closed されたものを再開する前に、rebase + 新たな検証エビデンスを要求してください。

自動化のオーバーライド

自動化の出力がレビューに副作用をもたらす場合に使用してください。

1. 誤ったリスクラベル: 意図した risk:* ラベルを設定してください。将来のリスク自動化が有効な場合は、risk:manual についても ラベル自動化コントラクト に従ってください。この上書きによって、risk:high OR domain:security の承認ルールが回避されることはありません。
2. 問題のトリアージで誤って自動クローズされた場合: 再オープンし、ルートラベルを削除して、明確化のためのコメントを1件残してください。
3. スパムやノイズへのラベル付け: 正規のメンテナーコメントを1つだけ残し、冗長なルートラベルを削除します。
4. PRのスコープが曖昧な場合: 詳細なレビューに入る前に分割を依頼してください。2つの関心事を同時にレビューしようとしないでください。

ハンドオフ

レビューを他のメンテナやエージェントに引き継ぐ際には、以下を含めてください：

1. スコープの概要。
2. 現在のリスク分類とその根拠。
3. 検証した内容。
4. オープンなブロック。
5. 推奨される次のアクション。

これにより、コンテキストの損失を抑え、次のレビュアーがすでにあなたが行ったフェッチを再度行わないようにします。

週次キューの保守

• stale キューを巡回します。status:no-stale の適用は、Project board contract のルールに従う場合に限ります。すなわち、accepted な作業やその他の長期にわたる作業に、オープンのまま維持すべき記録された理由があり、コントリビューターが確認できるルーティングの根拠があり、他の stale 除外がまだ適用されていない場合です。アクティブなリリーストラッカーや、アクティブな RFC・設計トラッカーは、issue 自体がアクティブな調整・決定の対象を明確に示している場合、デフォルトで stale 保護を維持できます。これらは、マイルストーンがクローズされたとき、トラッカーがライブ状態から乖離したとき、RFC が決定に達したとき・置き換えられたとき・クローズされたとき、または issue がアクティブなプロジェクトの決定対象を表さなくなったときに、再検討してください。stale 除外監査が導入されるまでは、これらの事実が欠けている既存の status:no-stale issue は、自動的な stale 候補ではなく、監査での指摘事項として扱ってください。
• まず size:XS または size:S のバグおよびセキュリティ関連の PR を優先してください。
• 頻繁に寄せられるサポートの質問を、ドキュメントの改善や自動応答のガイドラインへと変換する。

目標は、すべてのオープンなPRが、活発にレビューされているか、作者の対応待ちか、外部要因によってブロックされているかのいずれかであり、誰も手を付けなかったために放置されている状態が決してないキューを実現することです。