pr-splitter

PR Splitter

元の PR をソースとして保持し、意図的にレビューしやすい小さな PR に分割し、レビューのフィードバックに応じてスタックに生じる差分をローカルで追跡します。

必須のワークフロー

1. 履歴に手を加える前にスナップショットを作成する

   • git status を確認します。
   • 元のブランチへの変更されないローカル参照を作成します：git branch backup/original-large-pr。
   • 分割が完了するまで、元のブランチを削除したり書き換えたりしないでください。

2. 元の PR の内容を把握する

   • git diff --stat <base>...HEAD、git diff --name-only <base>...HEAD、git log --oneline <base>..HEAD を確認します。
   • 変更をレビュー単位で分類します：準備／リファクタリング、API／型の変更、動作、テスト、ドキュメント、クリーンアップ、生成ファイル／ロックファイル。

3. ローカルのスクラッチパッドを作成する

   • 分割メモをコミットしないローカルファイルに書きます。できれば .notes/pr-split.md を使用します。
   • .notes/ が無視されることを確認するか、追跡対象外のままにします。ユーザーから明示的に依頼されない限り、スクラッチパッドのメモはコミットしないでください。
   • 次の情報を記録します：元のブランチ、ベースブランチ、計画中の PR、抽出したファイル／ハンク、各 PR の検証内容、元の差分の残り、レビューのフィードバックによって意図的に生じた差分。

4. 分割方法を選ぶ

   • 後続の作業が先行する作業に依存する場合は、スタックされた PR を使用します。
   • 変更が本当に独立している場合にのみ、並列 PR を使用します。
   • 共有する準備変更によって独立した作業が可能になる場合は、基盤 PR と並列の後続 PR を使用します。

5. 変更を安全に抽出する

   • 乱雑な履歴を書き換えるよりも、適切なベースから新しいブランチを作成し、必要な変更だけを選択して復元する方法を優先します。
   • ファイルの所有範囲が明確な場合は、パス単位で抽出します：git checkout backup/original-large-pr -- path/to/file。
   • 複数の変更が混在するファイルでは、ハンク単位で抽出します：git restore -p --source backup/original-large-pr -- path/to/file。
   • 各 PR は個別にビルドでき、レビュー可能な状態にします。

6. 各 PR を個別に検証する

   • その PR の対象範囲に関連する、最も限定的なビルド、型チェック、リンター、テストを実行します。
   • 分割計画で明示的に指定されている場合を除き、検証対象のコードからテスト、ドキュメント、生成ファイルを切り離さないでください。

7. 差分を意図的に管理する

   • レビュアーが承認した変更を、スタックの新しい基準として扱います。
   • 先行する PR を変更した後は、それに依存する PR をリベースし、元のブランチの内容をそのまま優先するのではなく、レビュー済みの方針に沿って競合を解決します。
   • 進化するスタックと backup/original-large-pr を比較し、残っている意図を見つけます。バイト単位の完全一致を目指す必要はありません。
   • 意図的な差分を .notes/pr-split.md に記録します。

8. 書き換えたスタックには range-diff を使用する

   • リベース、競合解決、強制プッシュの後に git range-diff を実行し、何が変わったかを把握します。
   • スタックされた PR を更新する際は、重要な range-diff の結果をレビュアーに要約します。

PR の説明文のパターン

PR の説明文は簡潔にし、レビュアー向けに記載します。

## Summary

This is PR N of M split from a larger change.

## Scope

- ...

## Intentionally excluded

- Follow-up PR will handle ...

## Verification

- ...

分割の詳細な記録を PR の説明文に記載しないでください。抽出に関する詳細なメモと差分の追跡は .notes/pr-split.md に記録します。

スクラッチパッドのテンプレート

# PR split scratchpad

Original branch: backup/original-large-pr
Base branch: main

## Planned PRs

1. branch-name
   - Scope:
   - Files/hunks extracted:
   - Verification:
   - Changeset: (package names, bump type, scoped message)
   - Status:

## Remaining original intent

- ...

## Drift notes

- Date / branch / reason:

Changesets

各分割 PR には、その PR の変更に限定した独自の changeset を含める必要があります。元のブランチから changeset を引き継がないでください。これは結合された変更全体を対象としており、個別の分割 PR には適しません。

変更を分割ブランチに抽出した後は、次の手順に従います。

1. 元のブランチから引き継いだ changeset ファイルを削除します。 これらは結合された差分を対象として作成されており、不正確な変更履歴エントリが生成されます。
2. CLI を使って、各 PR 用の新しい changeset を作成します（.mastracode/commands/changeset.md を参照）。

   pnpm changeset -s -m "your scoped message" (--major | --minor | --patch) pkg-name
   

3. メッセージの対象を、その PR の変更だけに絞ります。 changeset のメッセージには、元の機能全体ではなく、この特定の PR が行う変更を記述します。
4. この PR で実際に変更したパッケージだけを含めます。 元の changeset に 5 つのパッケージが記載されていても、この PR で変更するのが @mastra/core だけなら、新しい changeset には @mastra/core のみを記載します。
5. バージョンの更新種別を PR の範囲に合わせます。 準備やリファクタリングの PR は通常 patch、新しい API を導入する PR は minor、破壊的変更を含む PR は major です。

忘れないよう、計画した各 PR の検証チェックリストの下にあるスクラッチパッドのテンプレートへ、changeset の作成を追加します。

よくある失敗

動作が複数のファイルにまたがるのにファイル単位で分割すること、コードなしでテストだけを抽出すること、後続の PR をコンパイルできない状態にすること、レビュアー向けの概要なしに強制プッシュすること、元のブランチを早期に削除すること、スタックの競合を解決する際にレビューのフィードバックを取り消すこと、各分割 PR で新たに対象を絞った changeset を作成せず、元のブランチの changeset をそのまま残すことは避けてください。

デフォルトの出力

PR の分割を依頼された場合は、次の内容を提示します。

1. 提案する PR の順序
2. ブランチ戦略
3. スクラッチパッドのパスと初期内容
4. 抽出コマンド
5. 各 PR の検証計画
6. 差分のずれを管理する計画