プルリクエストの書き方｜初めてのPRで伝える変更理由・確認結果

PRの説明が「件名を追加しました」だけだと、レビューする人は差分から目的や確認状況を探すことになります。何を書けば、変更を判断してもらいやすいのでしょうか。

以下は、問い合わせに必須・1〜100文字の件名を追加する架空例です。実在のPRや実行済みのテスト結果ではありません。

差分から見えない「なぜ」を一文で補う

「入力チェックを追加した」だけでは、仕様変更なのか、不具合修正なのかが分かりません。「空の問い合わせが保存されてしまうため、件名を必須にする」まで書くと、変更の理由が伝わります。

「依頼されたため」で止めず、誰が何に困り、どうなればよいかを補います。長い作業日記にする必要はありません。

Googleのガイドも、変更内容と理由を説明する考え方を示しています。ただし、Googleの書式がすべての職場の決まりではありません。自分のチームのテンプレートに合わせて使ってください。Google Engineering Practices

説明欄に揃える五つの判断材料

• 目的：件名を持たせ、一覧から内容を見分けられるようにする。
• 変更点：入力欄、保存時の検証、一覧表示など、変えた範囲。
• 確認結果：どの条件を、どの環境・方法で試し、どうなったか。
• 未確認：まだ試していないことと、その理由。
• 見てほしい点：判断に迷った箇所と、自分の案。

未確認を「問題ありません」に置き換えず、追加確認の要否と、誰がいつ確認するかを相談します。

見てほしい点は「全体」だけでなく、「既存の登録機能と検証の置き場所をそろえた点」のように具体化します。注目点を伝えることは、それ以外をレビュー対象から外すことではありません。

件名を追加するPRの記入例

次の「確認結果」は記入方法の例です。使うときは実際に行った確認へ置き換え、未実施のものは未確認へ移してください。

仕様や確認記録へのリンクは、チームが参照できるものを添えます。リンク先を開けない場合にも備え、目的の一文はPR内に残します。

この例だけでテストが十分とは限りません。既存データ、文字の数え方、別の登録経路、権限などで必要な確認は変わります。未決の仕様を、記入例に合わせて勝手に決めないようにします。

「テストOK」を条件と結果に分ける

「空欄では保存されずエラーが出た」「100文字では保存できた」のように、入力・操作と結果を対にします。

• 自動テスト：対象と実行結果を残す。成功しても、テスト環境で使えることまで確認したとは限らない。
• 画面確認：環境と操作を残す。スクリーンショットだけでは保存や権限の正しさを証明できない。
• 添付する記録：顧客情報や認証情報を含めない。追加修正の後は、古い確認結果をそのままにしない。

変更が大きくなる前に、分け方を相談する

作業中に見つけた名前の変更や共通化は、今回必要でなければ別にする案があります。GoogleのSmall CLsも、関連するテストを含む、自己完結した小さな変更を扱っています。行数だけで機械的に分ける考え方ではありません。

登録から一覧表示までが一緒でないと意味を確認できない場合は、ファイル単位の分割がかえって分かりにくくなることもあります。

送信前に、差分と説明を照らし合わせる

手元で編集した内容と、PRに入る内容は同じとは限りません。Git上の違いはstaged・unstagedの確認例でも確認できます。

まず「何を変えたか」の次に、「なぜ変えたか」を一文だけ足してみてください。