stacked PR で小さく出す — Graphite が解く問題と、要らない場合

解こうとしている問題

機能を1つ作ると、PRが1,000行を超えることがある。レビュアーは時間を確保できず、2日放置される。その間、次の作業を始めると、まだマージされていないブランチの上に積むことになり、後からの修正が面倒になる。

stacked PR は、1,000行のPRを200行×5本に分け、それぞれを前のPRの上に積む。レビュアーは200行ずつ見られるので着手しやすく、下から順にマージされていく。上のPRのベースは自動で追従する。

stacked PR 自体は Git の機能だけで実現できる。ブランチを連鎖させて、下のブランチが変わったら上を rebase すればよい。Graphite が売っているのは、この rebase の連鎖を自動でやることと、積まれたPRを一覧で見る画面である。

導入する価値がある条件

• 1つのPRが数百行を超えることが日常的にある
• レビュー待ちで手が止まることが週に何度もある
• レビュアーが限られていて、着手までに時間がかかる
• チーム全員が Git のブランチ操作に慣れている

4つめが前提条件である。stacked PR は Git の操作が1段複雑になる。rebase が何をするか理解していないメンバーがいると、コンフリクトの解消で履歴を壊す事故が起きる。導入前に rebase の挙動を共有する時間が必要になる。

向かない条件

次のいずれかに当てはまるなら、導入しても効果が出にくい。

• PRが元々小さい（100行以下が普通）→ 解く問題がない
• レビューが数時間で返る → 待ち時間の問題がない
• 1人開発 → レビュー待ちが発生しない（ただしPRを小さく保つ習慣としては有効）
• squash merge を必須にしている → 積んだ履歴の扱いに追加の設計が要る

3つめは補足が必要で、1人開発でもPRを小さく保つ習慣そのものには価値がある。後から変更を追うとき、200行のPRが5本あるほうが1,000行の1本より読める。ツールを入れるかは別として、分ける習慣は持っておくとよい。

PRを分ける単位

stacked PR の効果は、分け方で決まる。機械的に行数で切ると、途中のPRだけではビルドが通らない状態になり、レビューできない。分ける単位は次のようにする。

• 1本目：型定義とインターフェースの追加（既存の動作は変えない）
• 2本目：実装の追加（まだ呼ばれていない）
• 3本目：既存コードから呼び出すように変更
• 4本目：古い実装の削除

この分け方なら、各PRが単独でビルドが通り、テストも通る。「それぞれが独立してマージできる状態か」が、分け方が正しいかの判断基準になる。

マージキューとの関係

Graphite の上位プランにはマージキューが含まれる。複数のPRが並行してマージされるとき、それぞれは main に対してテストが通っていても、同時にマージすると壊れることがある。マージキューは1本ずつ順に main に当ててテストを通し、壊れたら止める仕組みである。

これが必要になるのは、1日に何本もマージされる規模からである。週に数本のチームでは、キューの待ち時間のほうが邪魔になる。チームの規模とマージ頻度で、必要かどうかが分かれる。

よくある質問

Q. GitHub の標準機能だけでできますか。

A. できます。ブランチを連鎖させて手で rebase すれば同じことです。ツールが提供するのは、その自動化と一覧性です。まず手でやってみて、面倒だと感じたら導入を検討する順序が合理的です。

Q. チーム全員が入れないと意味がないですか。

A. 自分のPRを小さく分けること自体は1人でもできます。ただしレビュアー側が積まれたPRの文脈を理解する必要があるため、レビューする側にも説明が必要です。