積み上げプル要求について

積み上げプル要求について

スタックされたプル要求は、同じリポジトリ内の 2 つ以上のプル要求です。次に示します。

• 最初または一番下の pull request は、スタックのトランク (通常はリポジトリの既定のブランチ ( mainなど) を対象としますが、リリース ブランチなどの任意のブランチを指定できます。
• 後続の各プル要求は、その下のプル要求の分岐を対象とします。

   ┌── feat/frontend     → PR #3 (base: feat/api-endpoints)  ← top
  ┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer     → PR #1 (base: main)               ← bottom
main (default base branch)

積み上げ分岐は依存関係チェーンを形成し、各分岐は、その下の分岐に基づいて構築されます。 共有型やデータベース スキーマなどの基本的な変更は下位ブランチに配置され、API ルートや UI コンポーネントなど、それらに依存するコードはより上位のブランチに配置されます。

スタック内の各プル要求は、1 つ以上のコミットの個別のレビュー可能な変更を表します。 各プル要求を個別に確認して反復処理できます。各プル要求には、そのレイヤーの差分と、その下のブランチとブランチの間の変更のみが表示されます。

重要な原則: あるレイヤーのコードが別のレイヤーのコードに依存している場合、依存関係は同じ分岐または下位の分岐にある必要があります。 これまでに作成した内容に依存する別の懸念事項を開始するときに、新しいブランチを作成します。 たとえば、バックエンドからフロントエンドの作業に切り替える場合、コア ロジックからテストに移行する場合、または現在のブランチが既に確認できる大きさである場合などです。

スタックプル要求 GitHub 使用する理由

1 つの変更を完了し、次の変更に直接移動します

スタック プル要求を使用すると、まだ開いているプル要求の上に新しいプル要求を開きます。 大規模なプロジェクトでは、次の変更は、まだマージされていない作業によって異なります。 マージを待つ代わりに、スタックを使用してビルドを続けることができます。

スタック内の各プル要求に 1 つの重点的な変更が含まれていると、レビュー担当者は、大きなプル要求ではなく、レイヤーごとに小さな差分を確認します。 プル要求が小さいほど、レビューが速くなり、スキミングされる可能性が低くなり、古くなり、マージの競合が発生する可能性が低くなります。

大量の開発に適しています

多くの場合、AI エージェントを使用して多数のコードを一度に生成すると、スタックによって各変更の実行場所が提供されます。 エージェントは 1 つのタスクを完了し、そのタスクに基づいて次のタスクを開始します。 このシーケンスはスタックに直接マップされます。タスクごとに 1 つの pull request が、それぞれ以下のものに基づいています。 スタックを使用すると、関連のない変更を 1 つのブランチに結合するのではなく、これらの依存関係を明示的に記録できます。

でスタック プル要求を使用する利点 GitHub

プル要求がスタックされていない場合、大きな変更をより小さい依存プル要求に分割すると、追加の作業が作成されます。

• ブランチ管理。 依存するプル要求間でブランチの再調整と同期の維持は面倒で、エラーが発生しやすくなります。
• 規則と CI。 ブランチ保護規則と CI チェックは、多くの場合、チェーン内の下位プル要求に対してのみトリガーされるため、残りの部分の真の状態を把握するのが難しくなります。
• コンテキストを確認します。 スタックの残りの部分からコンテキストから 1 つの変更を確認すると、レビューの品質が低下する可能性があります。

スタック プル要求では、プル要求のチェーンを接続ユニットとして扱い、各レイヤーを小さく集中させ、これらの問題に対処します。

リベイシング

リベイシングはスタックを操作する最も難しい部分であり、 GitHub はそれを自動的に処理します。 プル要求からサーバー側のカスケード リベースをトリガーすることも、gh stackの GitHub CLI 拡張機能を使用してローカルのカスケード リベースを実行することもできます。 スタックの下部にある pull request をマージすると、残りのブランチは自動的にリベースされるため、次のプル要求は既定のベース ブランチを対象とします。

スタック プル要求を使用できる場所

スタック プル要求は、次の場所で使用できます。

• GitHub CLI
• GitHub の Web サイト
• GitHub Mobile
• Webhook、REST API、GraphQL を使用したプログラムによるサポート
• エージェントの場合は、 gh-stack スキルを使用します

GitHub CLI 内

gh stackのGitHub CLI拡張機能は、ローカル開発ワークフローを処理します。 正しい依存関係の順序でブランチを作成および追跡したり、ブランチのリベースを維持したり、ブランチをプッシュしたり、プル要求を作成してリンクしたり、レイヤー間を移動することができます。 「Stacked pull requests CLI コマンド」を参照してください。

GitHub Web サイト

プル要求がスタックの一部である場合、次の情報が表示されます。

• プル要求の上部に、表示しているレイヤーを示す番号が付いたスタック アイコンが 。
• マージ ボックスにスタック マップが表示されます。 スタック内のすべてのプル要求とその状態が表示され、ワンクリックで任意のレイヤーに移動できます。 トランク (既定のベース ブランチ) は一番下にあり、スタック内の各プル要求は、その下のプル要求のブランチを対象とします。

Webhook、REST API、GraphQL を使用したプログラムによるサポート

スタック プル要求はプログラムで使用できるため、独自のツール、自動化、ダッシュボードに統合できます。

• Webhook には、stackイベント ペイロードにpull_request オブジェクトが含まれているため、プル要求の結合、移動、スタックからの退出時にオートメーションが応答できます。
• REST API は 、プル要求のスタック メンバーシップを読み取り、スタックの一覧表示、作成、拡張、およびディゾルブを行うエンドポイントを提供します。
• GraphQL API は 、読み取り専用の stack フィールドをプル要求で公開し、スタックとその中のプル要求の位置を照会します。

ルール、CI、マージ

規則と CI の適用

スタック プル要求では、 GitHub Actions ワークフローがサポートされます。

スタック内のすべてのプル要求のマージ要件は、最下位の pull request のベース ブランチ (通常は main) によって決定されます。

• CODEOWNER 承認などのブランチ保護規則は、スタック内のすべてのプル要求 (既定のブランチを直接ターゲットにしていないミッドスタック プル要求でも) に適用されます。
• 既定のブランチのプル要求によってトリガーされる CI チェックは、一番下の要求だけでなく、スタック内のすべてのプル要求に対して実行されます。

これにより、スタックのすべてのレイヤーが同じ品質バーを満たしてからマージできるようになります。

マージ

スタック全体、1 つのプル要求、または複数のプル要求にまたがるスタックの一部をマージできます。 スタック全体を一度にマージする必要はありませんが、プル要求は一番下からマージする必要があります。

• 上位の pull request をマージして、スタック全体を一度にマージします。 その下のすべてのプル要求がそれに付属しています。
• ミッドスタック プル要求をマージして、スタックの一部をマージします。 その下のプル要求もマージされ、上記のプル要求は開いたままになり、スタックのベース ブランチを自動的に再ターゲットします。

スタックはマージ コミット、スカッシュ、およびリベース マージ メソッドをサポートしており、マージ キューに対応しています。 結果のコミット履歴は、一番下から始まる各プル要求を個別にマージする場合と同じです。

次のステップ

• スタックプル要求のクイック スタート
• 積み重ねられたプル要求を組織にロールアウトする