github-pr-workflow

GitHub プルリクエストのワークフロー

追加の確認質問なしでレビュー担当者がマージできるプルリクエストを作成します。タイトルと本文で要点を明確に伝え、変更が機能する証拠を示し、フィードバックを受けたら適切に返信することが目的です。

使用する場合

• 機能として完成した変更のプルリクエストを作成しようとしている場合。
• レビュー担当者からコメントがあり、返信して修正をプッシュする必要がある場合。
• プルリクエストが1日以上オープンのままで、問題を解消して整える必要がある場合（古くなった競合、説明の不足、検証の不足など）。

使用しない場合

• 変更が機能としてまだ完成していない場合。まず作業を終えてください。レビューで差し戻されるドラフトプルリクエストはノイズになります。
• リポジトリが GitHub 以外のフォージを使用している場合。そのフォージの規約に合わせ、GitHub 固有の慣習を無理に持ち込まないでください。

作成前のブランチの整理

• ターゲットのベースブランチからリベースまたはマージし、差分を最新の状態にします。
• WIP コミットを、レビューしやすい単位にまとめます。論理的な変更ごとに1つのコミットにするのが望ましいですが、作業が実際に複数のステップに分かれる場合まで、必ずプルリクエストごとに1つのコミットにする必要はありません。
• テスト、型チェック、リンターがローカルでパスすることを確認します。意図的にスキップしたものがあれば、プルリクエストの本文に記載します。
• デバッグ出力、コメントアウトされたコード、追跡されていない TODO マーカーを削除します。

プルリクエストのタイトル

• 命令形で、70文字未満にします。
• 変更したファイルではなく、ユーザーから見える変更を先頭にします。Allow CSV export from reports table は Update reports.tsx より適切です。
• リポジトリに課題の接頭辞に関する規約（PAP-1234:、[security] など）がある場合は、それに従います。
• 末尾にピリオドを付けません。

プルリクエストの本文

次の構成を使います。

## Summary
- 1–3 bullets describing what changed and why.

## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.

## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.

## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.

明らかに軽微なプルリクエスト（誤字やドキュメントの修正など）に限り、Risk and rollback セクションを省略できます。

検証の証拠

• CI でテストがパスすることは必要ですが、それだけでは不十分です。変更がエンドツーエンドで正しく動作することも、レビュー担当者に伝える必要があります。
• UI の変更では、標準的な操作フローと1つのエッジケースのスクリーンショットを含めます。プロジェクトがダークモードとライトモードの両方に対応している場合は、両方のスクリーンショットを含めます。
• マイグレーションでは、ドライランの計画とロールバック手順を含めます。
• パフォーマンスの変更では、形容詞ではなく、変更前後の測定値を含めます。

レビューコメントへの返信

• すべてのコメントに返信します。「fixed in 」だけでもかまいません。返信のない修正では、レビュー担当者が推測することになります。
• レビュー中の修正は新しいコミットとしてプッシュします。レビュー担当者の同意がない限り、レビュー中に amend しないでください。
• フィードバックに異論がある場合は、理由を1文で伝え、判断はレビュー担当者に委ねます。コメントをめぐって対立を深めないでください。
• 変更をプッシュしたら、明示的に再レビューを依頼します。

マージ前のチェックリスト

• 必須のチェックがすべて成功している。
• すべてのレビューコメントが解決済みである。
• プルリクエストのタイトルと本文が現状に即している（レビュー中に範囲が変わった場合は更新する）。
• プロジェクトの規約に従い、関連付けられた課題が in_review または done に移行している。
• 長期運用の統合ブランチでない限り、マージ後にブランチを削除する。

アンチパターン

• 「コミットを参照」とだけ書かれたプルリクエストの説明。レビュー担当者がログを読む必要がないようにします。
• 本文で区別せずに、リファクタリングと動作変更を同じプルリクエストに混在させること。
• 無関係な編集をまとめた「フィードバック対応」コミット。フィードバックへの対応ごとに1つのコミットにするのは問題ありませんが、進行中のすべての変更を1つにまとめるのは避けてください。
• レビュー担当者に知らせず、レビュー中に強制プッシュすること。