make-pr-easy-to-review

PR をレビューしやすくする

レビュー担当者が意図、重要なファイル、リスクをすばやく理解できるように PR を準備します。既定の目標は、動作を変更せずにレビューしやすくすることです。

ワークフロー

1. ユーザーが指定した URL または現在のブランチから対象の PR を特定します。
2. コミット、差分の規模、変更されたパス、生成ファイル、PR の説明を確認します。
3. レビューしやすさに関する問題を特定します。ノイズの多いコミット、古い説明、無関係な変更、機械的な変更とロジック変更の混在、テストの不足、レビュー担当者が確認を始める箇所の不明瞭さなどです。
4. 履歴を書き換えたり、強制プッシュしたりする前に、計画を提案します。
5. 安全な改善を適用し、ツリーまたは差分が意図したコードと一致していることを確認します。

履歴の整理

ユーザーが依頼するか計画に同意した場合に限り、履歴を書き換えます。書き換える前に：

gh pr view <PR> --json title,headRefName,baseRefName,state,commits
git fetch origin <headRefName> <baseRefName>
ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})

通常、適切なコミットのグループ分けは依存関係の順に行います。

1. スキーマ／ストレージまたは生成された API 定義。
2. コアロジック。
3. 配線と統合。
4. UI または表層の動作。
5. テスト。

書き換えた後は、内容が一致していることを確認します。

echo "Original tree: $ORIGINAL_TREE"
echo "Current tree:  $(git rev-parse HEAD^{tree})"
git diff origin/<headRefName> --stat

ツリーが意図せず変更されていた場合は、プッシュしないでください。

レビュー担当者向けのガイダンス

コードの動作を変更しない場合は、PR の説明とレビュー用メモを活用してください。

• 実際の差分と一致する TL;DR を追加します。
• コアファイルと生成ファイルまたは機械的な変更を分けます。
• リスクのある動作変更、移行順序、ロールアウト計画、テスト範囲を明記します。
• 意図の説明に役立つ場合は、課題トラッカー、ダッシュボード、設計ドキュメントへのリンクを追加します。

ガードレール

• 意味のある動作変更を「整理」の中に隠さないでください。
• ユーザーが明示的に依頼しない限り、フックを回避しないでください。
• メモを添えてもレビューしやすくできないほど PR が大きい場合は、問題を取り繕うのではなく、分割を提案してください。