PR ワークフロー
master を対象とする PR に対するメンテナー側のガバナンス契約。ブランチ保護設定、DoR/DoD の準備状態に関する契約、および障害復旧プロトコルはここに記載されています。日常的なレビューは Reviewer Playbook で行います。コントリビューター向けのフローは How to contribute に記載されています。
ガバナンスの目標
このワークフローは、PRの量が多い場合でも以下の5つのことを維持するために存在します：
- マージのスループットは予測可能です。
- CIシグナルの品質が高く維持され、フィードバックが速く、偽陽性が低い状態。
- セキュリティレビューは、リスクのある表面に対して明示的に行われます。
- 変更は推論しやすく、元に戻しやすいです。
- リポジトリのアーティファクトには、個人データや機密データが含まれていません。
これを提供する制御ループは、意図的に階層化されています：
- 取り込み分類: パス／サイズ／リスクのラベルにより、PR が適切な深さへ振り分けられます。
- 確定的な検証: マージゲートは、主観的なコメントではなく、再現可能なチェックに依存します。
- リスクベースのレビュー深度: 高リスクの影響とセキュリティ境界は入念にレビューし、低リスクの作業は迅速に進める。
- ロールバック優先のマージ契約: すべてのマージパスには具体的な復旧手順が含まれます。
自動化は、パス/スコープラベル、手動の issue-dashboard 計画レポート、CI ゲーティングを処理します。リスク、サイズ、種類、コントリビューター層のラベルは、保守対象のワークフローが明示的に担当している場合を除き、メンテナーによる受け入れ時の判断です。最終的なマージの責任は、人間のメンテナーと PR 作成者にあります。risk:high または domain:security のいずれかを含む PR には、綿密なレビューと、独立した Core Team の承認2件が必要です。自動レビューは Core Team の承認として数えられません。
プロジェクトボードコントラクト
Project ボードは自動化された計画用ボードであり、信頼できる PR レビューキューではありません。
ボードは、課題の対応準備状況、ルーティングの根拠、ロードマップのグループ化、依存関係、ブロッカーの状態、stale 除外の理由に使用します。これらのシグナルは変化が緩やかなため、ボードフィールドやプランニングレーンが有用な状態を保てます。
現在の自動化は手動かつレポート専用です。project-dashboard-plan.yml は単一の issue 番号に対して workflow_dispatch で実行され、issue のペイロードを読み取り、その issue の現在のラベルと状態に最も一致する既存の Project Status 値を提案するステップサマリーを書き込みます。Project フィールドの書き込み、issue の編集、ラベルの追加、コメントの投稿、または issue イベントでの自動実行は行いません。
この計画分割の JSON サマリーは project-board-contract.json にあります。これを report-only プランナーおよび将来のボードリフレッシュ自動化の契約として扱い、自動 issue-event 実行やアクティブな GitHub Project ミューテーションの承認としてはまだ扱わないでください。ライブの ProjectV2 書き込みには、承認済みのフィールドマッピング、プロジェクトスコープのクレデンシャルまたはアプリインストール、および計画ステータスとライブの Project 状態を比較するリードバックが、メンテナーがそれに依存する前に必要です。
ネイティブ PR レビュー状態を手動ボードのレーンにミラーリングしないでください。GitHub PR の状態が、レビュー判断、必須チェック、マージ可能性、コンフリクト、古い承認、およびマージ準備状況を所有します。ボードが後で DIRTY、BEHIND、APPROVED などの派生的な PR ルーティングを表示する場合は、それを別個の信頼できる情報源ではなく、GitHub 状態のダッシュボードビューとして扱ってください。
ボードを有用に保ちつつ、プッシュ、レビュー、CI 実行のたびにメンテナーが更新する必要をなくします。
サイズとリスクの自動ラベル付けは、ワークフロー上は別の問題です。#9345 は PR の更新時に決定論的なサイズラベルを再計算することがあります。そのリスク分類器は、メンテナーが根拠を確認し、リスクラベルの変更を別途有効にするまで、レポートのみの状態です。リスクの自動化は、メンテナーがその上書きを削除するまで risk:manual を尊重する必要があります。issue-dashboard planner は PR のリスク、サイズ、タイプのラベルを適用または再計算しません。
課題ルーティングのエビデンス
Issueのトリアージは引き続きメンテナー全員の共同責任です。受理されたIssueをオープンのまま維持するために、事前に固定の担当者マップを用意する必要はありません。また、CODEOWNERSによって、コードオーナーが該当領域のすべてのIssueに対して責任を負うわけではありません。
通常のレビューや stale スイープから特殊な状態によって隠れてしまう Issue には、コントリビューターから見えるルーティングの根拠が必要です。具体的には、status:no-stale、有効なリリース/RFC/設計トラッカーのステータス、または保留中のメンテナー判断などです。status:blocked はよりシンプルなルールを維持します。未解決のブロッカーを記録し、ブロッカーが解消された時点で stale 保護を再検討してください。
これらの意味を一貫して使用してください。
| ルーティングシグナル | 手段 | 以下を意味するものではありません |
|---|---|---|
| 担当者 | 誰かが当面の作業を積極的に実装、調査、または推進しています。 | 関連するすべての課題に対する恒久的な領域の所有権または受動的な責任。 |
| ルーティングの根拠 | 可視のissueコメント、本文セクション、公開フィールド、ボードフィールド、またはリンクされたトラッカーが、特別な処理の理由と次の意思決定の場面を記録します。 | 自動実装オーナーシップまたは恒久的なエリアオーナーシップ。 |
| トラッカー/RFC サーフェス | アクティブなリリーストラッカー、RFC、または設計トラッカーは、それが最新である限り、調整の場として機能します。 | トラッカーが閉じたり、ずれたり、アクティブな決定を表さなくなった後の恒久的な失効保護。 |
| プロジェクトボードのフィールド | 計画の準備状況、ルーティングの根拠、ブロッカーの状態、または陳腐化の除外理由に関する任意の計画シグナル（可視かつ維持されている場合）。 | ネイティブPRレビュー状態のプライベートな失効ポリシーソースまたは代替。 |
| ラベルと CODEOWNERS | 永続的な分類、想定される領域へのルーティング、PR レビューのコンサルテーションヒント。 | 所有権または古いデータからの保護をそれ自体で行います。 |
CODEOWNERS は、PR レビューのルーティングを行う仕組みです。問題が明らかに特定のパスに関係する場合に相談すべき担当者を特定できますが、issue の所有権を生み出すものではなく、プライベートなルーティングマップとして古いポリシーに反映すべきではありません。
ルーティングの根拠は、配信の所有権ではなく、次の意思決定に関するものです。ルーティングされたIssueは「所有された」まま宙ぶらりんの状態にすべきではありません。次に表示される更新では、以下のいずれかの結果を明示する必要があります。アクティブな実装者をアサインする、Issueをコントリビューターが対応できる状態にする、トラッカーまたはマイルストーンにルーティングする、ブロッカーを記録する、具体的なメンテナーの意思決定ポイントをスケジュールする、または根拠とともにクローズ/延期する。
課題をメンテナーのトリアージに割り当てることが妥当なのは、その課題にどのような決定が必要か、その決定がどこで追跡されるか、いつ再検討されるかが記録されている場合に限られます。トリアージのパスが完了したら、トリアージのルーティングを、アクティブな実装担当者、コントリビューター対応可能なスコープ、トラッカーまたはマイルストーンのルート、ブロック中/保留中の状態、またはクローズ理由に置き換えてください。
保護された issue については、status:no-stale を追加または維持する前に、stale 除外の理由と次の判断ポイントの両方を記録してください。有用な可視のエビデンスソースには以下が含まれます:
- 担当者がアクティブな作業を行っており、かつ古い処理を適用すべきでない理由を説明する issue で確認可能なメモ、本文セクション、またはトラッカーのエントリがある場合。
- 古い除外（stale-exemption）の理由と次の決定対象を記録する issue コメント、issue 本文セクション、または公開 issue フィールド。
- 通常のissue閲覧者に表示され、積極的にメンテナンスされている公開Projectフィールド。
- この問題が未解決のままである理由と、いつ再検討すべきかを記録した、リンク済みの公開トラッカー、マイルストーン、RFC、または設計上の課題。
アクティブなリリーストラッカーおよびアクティブな RFC・設計トラッカーは、永続的な調整の場です。issue のタイトル、本文、ラベル、またはマイルストーンがアクティブなトラッカーまたは RFC を明確に示している場合、トラッカー自体が stale 免除の理由とコントリビューターに可視な振り分けの場を提供するため、issue ごとに繰り返しコメントする必要はありません。マイルストーンがクローズされたとき、トラッカーが現行のリリース状態から乖離したとき、RFC が決定に達した・置き換えられた・クローズされたとき、または issue がアクティブなプロジェクト決定の場を表さなくなったときに、免除を見直してください。
トラッカーマーカーラベルが必要な場合は、type:tracker を使用します。これは、リリーストラッカー、ロードマップまたはエピックトラッカー、RFC/設計トラッカー、実装バッチトラッカー、クリーンアップトラッカー、監査トラッカーなど、issue のみの親調整サーフェスに適用されます。通常の子 issue、通常の機能リクエスト、バグ、PR、またはトラッカーから単にリンクされているだけの項目には適用しないでください。type:tracker は、人間や自動化が親サーフェスを見つけるのに役立ちます。ただし、これは必須の stale 免除理由、次の決定サーフェス、マイルストーン、担当者、またはクローズ基準の代わりにはなりません。ライブラベルがまだ存在しない場合は、roadmap、type:roadmap、またはその他のエイリアスで代用せず、別の正確なラベルパケットを通じて正規ラベルを作成して移行してください。
これらのいずれも存在せず、その issue がアクティブなトラッカーや RFC でない場合でも、トリアージを継続している間は issue をオープンのままにできますが、status:no-stale を恒久的な保護手段として頼るべきではありません。stale-exemption 監査が導入されるまで、理由やルーティングの証拠が欠落していることは監査の指摘事項および修正提案であり、自動的な stale-closure のトリガーにはなりません。
名前付きマイルストーンポリシー
名前付きマイルストーンは、能力ドメイン内の限定された成果を対象とする有限の提供単位であり、恒久的なドメイン別バックログではありません。このポリシーでは、名前付きマイルストーンは番号付きリリースではなく、成果を中心に編成します。Parking Lot と Icebox は保留領域であり、名前付きマイルストーンではありません。新しいマイルストーンにはそれぞれ Domain: Bounded Outcome という名前を付けます。Auth のような広範で再利用可能な名前よりも、RPC Client: Authentication & Authorization を優先します。複合タイトルは、そこに含まれる各ドメインを占有します。
オープンしているすべての名前付きマイルストーンをアクティブとして扱う。別のマイルストーンをオープンする前に、メンテナーは追加するコホートの調整とレビューに必要なキャパシティがあることを明示的に確認しなければならない。そのコホートを待機させられない理由と、現在のマイルストーンのうち次にクローズする見込みのものを記録する。キャパシティを使い切った場合は、いずれかのマイルストーンがクローズするか、提案された作業が既存のコホートに統合されるまで、別の名前付きマイルストーンをオープンしてはならない。メンテナーの対応可能性またはレビュー負荷が大きく変化するたびに、キャパシティを再評価する。
各ドメインでアクティブな名前付きマイルストーンは1つまでにします。追加の調整コストが正当化される理由を意思決定に記録することを条件に、明示的なメンテナー例外によって、同じドメイン内の独立した成果を並行して進めることを許可できます。
名前付きマイルストーンには、明示的なスコープとクローズ条件が必要です。ただし、期限は任意です。一時停止中のコホートをオープンのままにしないでください。未完了の作業を振り替え、マイルストーンをクローズします。名前付きマイルストーンをクローズする前に、未完了の issue をすべてクローズまたは振り替え、成果が完了、キャンセル、または後継に置き換えられたかを記載したクローズノートを追加します。クローズした名前付きマイルストーンはクローズしたままにします。後続作業で新しい名前付きマイルストーンを作成できるのは、別の有限な成果を定義できるだけの、一貫した十分なスコープがある場合に限ります。そのマイルストーンには成果に基づく名前を付け、デフォルトで継続的な v2、v2.1、または同様の後継を作成しないでください。
GitHub では、issue または pull request は 1 つのマイルストーンにのみ所属できます。名前付きコホートを完了するために必要な作業は、番号付きリリースに含まれる場合でも、完了するまでその名前付きマイルストーンに置きます。リリースへの含有は、リリーストラッカーと変更履歴に記録します。名前付きコホート外の緊急バグ、メンテナンス、その他のリリースに紐づく作業には、番号付きリリースのマイルストーンを使用します。
名前付きマイルストーンがアクティブになったら、明示されたコホートを完了するために必要な作業（直接のスコープ、ブロッカー、依存関係、リグレッション）に新規受付を限定します。その他の作業は意図に応じて振り分けます：
| 宛先 | 用途 |
|---|---|
| 現在の名前付きマイルストーン | マイルストーンで定義されたコホートを完了するために必要な作業。 |
| 番号付きリリースマイルストーン | 指定されたコホート外の、緊急のバグ修正、メンテナンス、その他のリリースに伴う作業。 |
| RFC または設計上の問題 | 設計またはガバナンスの方向性が定まっていない作業。 |
パーキングロット | メンテナーが次の具体的な配置先を決定するまでの短期的なルーティング。 |
Icebox | 現在のコホート外で、直近に予定されていない、アクティブな名前付きマイルストーンを持つドメインに対する有効な将来の作業。 |
PRレーン
PR レーン（lanes）は、レビューの分配に関する期待値であり、必須ラベルの別系統ではありません。PR にどれだけのレビューの深さ、順序付け、メンテナの注意が必要かを判断するために使用します。実際の分配データは、CODEOWNERS、ネイティブの GitHub レビュー状態、CI、ラベル、リンクされた issue、明示的な関係キーワードが引き続き担います。
| Lane | 一般的な例 | 予想される動き |
|---|---|---|
| A: メンテナンス用ファストレーン | ドキュメントのみの修正、動作を変更しない小規模なテスト、メタデータ/テンプレートの修正、限定的な例、権限とリリース動作を維持するCI/ツールの修正 | 最軽量のレビュー。CI、テンプレート、ラベル、プライバシーチェックがクリーンであれば迅速にマージ。通常は risk:low および size:XS または size:S。 |
| B: 狭いバグ/修正レーン | 明確な失敗動作を伴う小規模なバグ修正、的を絞った検証を伴うプロバイダー/チャネル/ツールの個別修正、報告されたパス以外の動作を維持する互換性修正 | リスクや所有権の観点から別途必要となる場合を除き、サブシステムに精通したレビュアー1名による通常レビューを行います。リンクされた課題が実際に解決され、検証結果が信頼でき、CIがグリーンであればマージします。 |
| C: 機能スライスレーン | 機能追加作業、新しいプロバイダー/チャネル/ツールのサポート、新しい設定項目、限定的なユーザー向け動作変更 | 通常のレビューに加えて、境界固有の検証を行います。マイルストーンとの整合性が重要であり、PR ではトラッカーを実装するのか、依存するのか、関連するのかを明記する必要があります。 |
| D: アーキテクチャ、移行、強化レビューのレーン | 信頼、認証情報、互換性、ガバナンス、リリース権限、移行、ライフサイクル、永続化、権限、またはツールチェーンの最低水準に関する具体的な境界；risk:high または domain:security を付けた PR | 綿密なレビュー、変更されたリスクに対応する根拠、ならびにロールバックおよび互換性の分析。risk:high または domain:security を付けた PR には、独立した Core Team の承認が 2 件必要です。 |
| E: 置換、差し替え、重複レーン | 同じ問題を解決する複数のPR、古いPRを置き換える新しいPR、別のPRから引き継がれたコントリビューターの作業、現在のmasterによって陳腐化した古いPR | 詳細なレビューの前に調整してください。可能な場合は1つの正規パスを選択し、Supersedes #N は正確な場合にのみ使用し、作業が実質的に引き継がれる場合は帰属を保持してください。 |
これらのレーン用に別個の手動PRボードを構築しないでください。ただし、ネイティブのGitHubの状態とCODEOWNERSがルーティングの問題に答えられなくなった場合を除きます。通常のレーンレビューの前にネイティブのGitHubマージ状態を確認してください。DIRTYはまずコンフリクトを解決する必要があることを意味します。BEHINDのみの場合はマージ可能性の整理作業であり、作成者向けのブロッカーではありません。
必要なリポジトリの設定
master ブランチの保護:
- マージ前にステータスチェックを必須にする。
CI Required Gateのチェックを必須にする。- マージ前にプルリクエストのレビューを必須にする。
- 保護対象パスについては CODEOWNERS のレビューを必須とします。
.github/**（.github/workflows/**を含む）は.github/CODEOWNERSに記載されたメンテナーが所有しているため、ワークフローの変更には所有メンテナーのレビューが必要です。 - ブランチ／ルールセットのバイパスは組織オーナーに限定してください。
- 新しいコミットがプッシュされたら、古い承認を無効にします。
- 強制プッシュを制限する。
- すべてのコントリビューターのPRは
masterに直接ターゲットされます。
準備完了の定義（DoR）
レビューを依頼する前に、PRには以下のすべてが含まれている必要があります：
- PRテンプレートが完全に完了しました。
- スコープの境界を明確にする（何が変わったか／何が変わらなかったか）。
- 検証エビデンスを添付。CI が確認するのではなく、実際のコマンド出力を添付します。
- セキュリティとプライバシー、互換性、および（リスクを伴うパスの場合は）ロールバックの各フィールドが記入済みです。
- プライバシーおよびデータ衛生のルールを満たし、中立的でプロジェクトスコープのテスト文言です。プライバシーを参照してください。
- やむを得ない場合のアイデンティティに関連する表記には、ZeroClaw / プロジェクト固有のラベルを使用します。
完了の定義（DoD）
マージ前：
CI Required Gateがグリーンです。- 必須レビュアーの承認済み（CODEOWNERS で指定されたパスを含む）。
risk:highまたはdomain:securityを付与した PR には、Core Team による独立した承認が 2 件ある。 - リスクラベルは、コンポーネントの大まかな場所ではなく、実際の差分とその影響に対応します。ラベルを参照してください。
- 移行/互換性の影響は文書化されています。
- ロールバックパスは具体的で高速です。
メンテナのマージチェックリスト
すべてのマージ:
- スコープは焦点を絞り、理解しやすい。
- CIゲートがグリーンです。
- ドキュメントが変更された場合、ドキュメント品質チェックはグリーンになります。
- セキュリティとプライバシーのフィールドは完了しており、証拠は削除/匿名化されています。
risk:highまたはdomain:securityが付いた PR には、Core Team の独立した承認が 2 件必要です。自動レビューは承認数に含めません。- エージェントワークフローのノートは、再現性のために十分です（AI支援の場合）。
- ロールバックプランは明示的である。
- コミットタイトルは Conventional Commits に従います。
本文にコミット履歴をすべて保持したスカッシュマージ。squash-merge スキルは、紫色の Merged バッジと conventional-commits 形式の本文の両方を生成します。呼び出し方法については Skills を参照してください。
AI / エージェントの貢献ポリシー
AI支援のPRは歓迎します。レビューもエージェント支援で行うことができます。
必須:
- PRの概要をスコープの境界を明確にして整理する。
- 明示的なテスト/検証証拠。
- 危険な変更に対するセキュリティ影響とロールバックに関する注意事項。
推奨:
- 自動化が変更内容に大きな影響を与えた場合の、ツールやワークフローに関する簡易メモ。
- 再現性のためのオプションのプロンプト/プランのスニペット。
私たちは、コントリビューターにAIと人間の行の所有関係を数値化するよう要求していません。差分と検証証拠がその役割を果たします。
AIを多用したPRでは、レビュアーは以下に焦点を当てます：
- 契約の互換性。
- セキュリティ境界
- エラー処理。
- パフォーマンスとメモリの劣化。
- 著者が動作や影響範囲に関する質問に回答できるかどうか（意図の理解）。
SLAとキューの優先順位を確認する
- 最初のメンテナーのトリアージの目標：48時間以内。
- ブロックされたPRには、部分的なレビューのシリーズではなく、1つの実行可能なチェックリストコメントが表示されます。
status:no-staleは、受け入れ済みまたはその他の長期的な作業のうち、stale 免除理由が記録されており、かつ当該 issue が他の stale 除外によってまだ保護されていない場合に貢献者が確認可能なルーティング証跡を備えたものに対して予約されています。アクティブなリリーストラッカーおよびアクティブな RFC・設計トラッカーは、アクティブである限り、トラッカー自体をその確認可能な理由およびルーティング面として使用できます。これらの事実を欠く既存の免除は、stale 免除修復パケットが反映されるまで監査指摘事項となります。
スタックされた作業では、レビュー順序を決定論的にするために、明示的な Depends on #... を必要とします。
その決定論的な順序を運用に適用します。親を優先し、子より先にレビューします。親がレビュー可能でない場合は、範囲が限定された独立したスライスが早期レビューによって有益になる場合を除き、子の詳細なレビューを延期します。親が取り込まれた後、子を更新して再検証します。親がレビュー可能になったからといって、以前に収集した子の証拠が最新になるわけではありません。
稼働中の GitHub キューをレポート専用でスナップショット取得するには、python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table を実行します。--queue の値は near-ready、maintainer、second-core、author-action、stacked、mine、all です。--format には table、json、links を指定できます。near-ready は、GitHub 検索ステータスが成功している PR に対象を絞って maintainer レーンを狭めるため、メンテナーはマージ前の作業が少なくて済む可能性のある候補から着手できます。ただし、これはマージ可能性や承認が十分であることを確定するものではありません。all は共有レーンを個別に実行するため、1 つの PR が複数のレーンに表示される場合があります。mine レーンを含めるには --author LOGIN を追加します。候補リストは GitHub 検索から取得されます。未回答のリクエストの経過時間を推定するためにタイムラインの詳細を読み取るのは author-action のみで、現在のヘッドに対する Core の承認を 1 件見つけるためにレビューを読み取るのは second-core のみです。このコマンドはキュー状態を書き込んだり GitHub を変更したりすることはなく、欠落している、またはあいまいな詳細は不明として報告します。これは作業選択の補助であり、マージ準備完了の根拠ではありません。
置換には明示的な Supersedes #... が必要です。寄稿とテンプレートのルールについては、PRの置換 を参照してください。
レビュアー側のキュー管理、バックログの整理順序、古いものの扱い、ラベルの整備については、Reviewer Playbookを参照してください。
セキュリティと安定性のルール
これらのパスには境界に関係する挙動が含まれていることが多いため、注意深く確認してください：
crates/zeroclaw-runtime/（src/security/を含む）crates/zeroclaw-gateway/(イングレス、認証、ペアリング)crates/zeroclaw-tools/(実行可能なものすべて).github/workflows/とリリースパイプライン
パスの場所だけでは risk:high は選択されません。実際の差分とその影響を Labels → Risk labels に基づいて分類してください。信頼、認証情報、互換性、ガバナンス、リリース権限、または分野横断的なセキュリティ境界に関わる変更は、PR に risk:high または domain:security が付いている場合、詳細なレビューを受けます。
これらのクレート内のファイルシステムアクセス境界やネットワークまたは認証の動作には、差分が小さくても特に注意を払う必要があります。
risk:high または domain:security PR に必要な最低限の内容: 脅威またはリスクの記述、緩和策の注記、ロールバック手順、および Core Team による独立した 2 件の承認。
risk:high または domain:security PR に推奨: 境界動作を検証する焦点を絞ったテストに加え、想定される劣化を伴う明示的な障害モードのシナリオを 1 つ。
これらの境界をまたぐエージェント支援のコントリビューションについては、レビュー担当者は、著者が検証結果を貼り付けるだけでなく、実行時の動作と影響範囲を説明できることも確認します。
障害復旧
マージされたPRが回帰を引き起こした場合:
masterに対して直ちにリVERTしてください。- 根本原因分析を含むフォローアップのイシューを開く。
- 失敗モードをカバーする回帰テストのみを含めて、修正を再導入してください。
完璧な修正を待つよりも、サービスの品質を迅速に回復させることを優先してください。
このページでカバーしていない内容
- 日々のレビュー手順: Reviewer Playbook と PR Review Protocol を参照してください。
- ラベルのしきい値と定義: Labels を参照してください。
- プライバシーと PII のルール: Privacy を参照してください。
- 置き換えの帰属とテンプレート: Superseding PRs を参照してください。
- CIワークフローの一覧とトリアージ: CI & Actions を参照してください。
- リリース手順: Release Runbook を参照してください。