プルリクエストの説明欄に記載すべき内容

私が他の開発者にコードレビューを依頼する際に、プルリクエストの説明欄に記載している項目を紹介します。必ずしも全てのプルリクエストに全ての項目を記載しているわけではなく、タスク内容や状況によって使い分けています。説明欄が充実しているプルリクエストは、自分がレビューを依頼された側になった時に内容を把握しやすいので、自分が相手に依頼する時も同様のことを心がけています。

理想は、関連するチケットの説明欄やコメントを読まなくても、プルリクエストの説明欄を読んだだけでコードレビューの事前準備が整うようなレベルで記載があることです。とは言っても、そこまで書くとなると実装者側の負担も増えますし、タスクチケットの内容と重複する箇所も多くなるので、試行錯誤しながら自分たちのチームで適切だと思えるバランスを見つけるのが良いかと思います。

プルリクエストに内容の説明を書くのは、レビューワーに対する最低限の礼儀かと思いますし、将来的に過去のプルリクエストを調べる際に、内容がわからなくなることを防ぐという意味でも有効です。

プルリクエストの概要

レビューワーがそのプルリクエストがどのような内容なのかを大まかに把握出来るように、概要を簡潔に記載します。

例を上げると以下のようなものがあります。

バグ修正のプルリクエスト

どのようなバグを修正したのか、どこの画面で起こっていたのかを伝えるためのURL。

記載例：

在庫引き出しの際に、レース・コンディションが起きており本来の在庫数以上の数が引き出されていたので修正した。
対象URL：https://example.com/inventories/new

新機能のプルリクスト

どの画面にどのような機能を追加したのか。画面URLもしくはパスを記載。また、適切であれば受け入れ基準も記載。

記載例：

管理画面の記事一覧に記事検索機能を付けた。
対象URL：https://example.com/posts

受け入れ基準

・記事のタイトル、日付、本文の３つのフィールドで検索出来ること。

・１つのページの検索結果は最大２５記事とする。

対応内容

新機能の要件やバグの原因について説明するとともに、どのように対応したのかを具体的に記載します。

記載すべき内容はタスクの内容により千差万別ですが、いくつか代表的な例を紹介します。

どの画面に機能を追加したのか。

例：この機能が表示されるのはブログ管理サイトの記事一覧と編集ページのみです。

複雑なコードであれば処理の流れを説明する。

例：認証サーバーからアクセストークンを取得した後に、APIエンドポイントにアクセスし、取得した情報をデータベースに保存しています。

バグが起こる流れやコード箇所を詳細に説明する。

例：最初のリクエストが商品モデルの在庫数バリデーションを通過してDBに保存される前に、別のリクエストも同じバリデーションを通過しているため、重複したレコードがDBに保存されてしまう。

バグのログを貼る。

バグ検知システムやローカルで再現した時のログ（スタックトレース）を貼り、どのファイルの何行目で起きたバグの修正ということをわかりやすくする。

リグレッションが起こったgitコミットIDを記載する。

例：このリグレッションは、foo機能を開発時のコミットID〜にて発生しました。

機能が発動する条件やパターンを説明する。

例：この消費税率計算機能は、課税業者フラグが立っている会社モデルで2023/10/1以降のみで実行されます。

影響を受けるデータベーステーブルやカラムをリストアップする。

例：このバッチジョブで更新されるのは以下のDBテーブルです。

どのコミットでどのフィードバックに対応したか。

これは初回のプルリクエスト承認後にビジネスレビューで指摘があったため、別のプルリクエストを作成したような場合です。各指摘に対してどのコミットで対応したかを記載しておくと、全ての指摘事項を網羅できているかをレビューワーが判断しやすくなります。

例：指摘１に対してはコミット~（コミットリンク）で対応。

システムの観点からは対応した方が良いが、ビジネス上の理由で対応しなかったもの。

例：理想的にはこのデータベースカラムはNULLを許可しないような設計にすべきだが、既存の取引先のデータ入力が終わるまではその制約は追加しない。

機能削除のタスクで、どのように削除対象コードをピックアップしたか。

例：「git log –grep=実装ブランチ名」を使って実装コードが含まれるコミットを抽出した。

動作確認

自分が実装者としてどのように動作確認したか、もしくはレビューワーがコード確認と合わせてどのように動作確認をすべきかを記載します。

自分が行った動作確認をどのように伝えるべきかはタスクの性質によりますので、様々なテストパターンを網羅したことをテキストで箇条書きにした方が良いこともありますし、スクリーンショットや動画ファイルを添付して視覚的に伝えた方がわかりやすい場合もあるでしょう。

例えば消費税の計算タスクだったとして、内税・外税など合計でいくつのパターンで計算したかなどはテキストの方が伝わりやすいでしょう。

一方、デザイン変更や画面遷移が必要な機能などはスクリーンショットや動画の方が適切な場合が多いでしょう。

また、PDFやCSVなどファイルを生成するタスクであれば、開発環境で生成されたファイルを添付するのが直接的でわかりやすいかと思います。

なお、レビューワーに動作確認の方法を伝える場合は、テキストで画面遷移の方法を伝えたり、スプレッドシートにテストケースを記載して添付したりします。

まとめ

プルリクエストの説明欄の内容が充実していると、無駄な質疑応答のコミュニケーションコストを減らせたり、レビューワーがコードの内容を理解しやすくなってレビュー時間の短縮につながったりといった効果があります。

自分がレビューワーだったらどういう内容がプルリクエストに記載してあるとうれしいかを考え、相手にコードレビューを依頼する時は同じように丁寧に内容を説明することを心がけたいものです。

エンジニア術