私はふだんの開発でGitHub上でプルリクエストを出すとき、なんとなくフォーマット化したものを使っていました。プルリクエストについて整理するために、この記事でプルリクエストとはなんなのか、誰が読むのか、目的はなにか、書くべきことなどをまとめてみました。
記事の後半にはプルリクエストのテンプレートもありますので、よりよいプルリクエストにするための参考になればうれしいです。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
プルリクエストの書き方とは
ここでいうプルリクエストの書き方とは、プルリクエストの本文についての書き方のことです。プルリクエストの本文は、ひとことで言うと「ファイルの変更について表した文章」といえます。
プルリクエストの本文には、一般的には変更の概要や変更点、再現手順などが書かれます。自由に書けますが、気をつけるべきポイントもあります。人それぞれ、チームそれぞれで書き方はあると思いますが、よりよくしたいときにこの記事が参考になればと思います。
この記事では、プルリクエストのコードについては言及していません。たとえば「変更の目的はひとつであるべき」や「差分を小さくすべき」といったことについては書いていません。
この記事で想定している読者
この記事は、GitHubを用いて開発するエンジニアの方を想定して書いています。とくにチームで開発している方にとって有用だと思います。またプルリクエストと聞くとGitHubですが、Bitbucketなど他のプラットフォームを利用している方にとっても参考になると思います。
プルリクエストの書き方を気をつけるべき理由
プルリクエストの本文を書く上で気をつけるべき理由として、大きく次の3つがあります。
- 読むコストを下げるため
- いいフィードバックをもらうため
- プルリクエストはドキュメントでもあるため
1. 読むコストを下げるため
プルリクエストのレビューは時間がかかりますし、頭も使います。レビュワーの方が内容をできるだけ早く、ラクに把握できると、プロダクトの価値向上など他のことに時間を使えるようになります。
コミュニケーションコストも減るので、早いレビューにもつながります。なかなかレビューされないと、コンフリクトが起きて自分がつらい目にあってしまうかもしれません。
2. いいフィードバックをもらうため
プルリクエストの変更の内容が分かりやすかったり、とくに見てほしいポイントが明確だと、よりよいフィードバックにつながるかもしれません。
3. プルリクエストはドキュメントでもあるため
開発や運用のためのドキュメントと同じく、プルリクエストもドキュメントの一部です。将来のメンバーがあるコードに関わるときに、関連するプルリクエストを見ることもあります。今プロダクトに関わっている人だけではなく、あとから読む人のことも想定した内容であるべきといえます。
プルリクエストは誰のために書くのか
プルリクエストの本文は、次の方を読者として想定しながら書くと、よいプルリクエストにつながります。
- レビュワーのため
- 自分のため
- 将来のメンバーのため
レビュワーのために書く、というのは分かりやすい理由だと思います。自分のために書くと、プルリクエストに問題がないかを確認することができます。また、前述したように将来のメンバーのためにも書きます。これはプルリクエストに前提知識がいらないように書く、などの気をつけるポイントにつながります。
プルリクエストの書き方
それでは、プルリクエストの本文になにを書くかについてまとめます。プルリクエストの本文には、次のような項目を書いていくといいです。
| 順番 | 見出し | 備考 |
|---|---|---|
| 1 | 変更の概要 | 概要、関連するIssueやプルリクエスト |
| 2 | なぜこの変更をするのか | - |
| 3 | やったこと | チェックボックスで進捗を表す |
| 4 | 変更内容 | UIのスクリーンショット、APIのリクエスト/レスポンスなど |
| 5 | やらないこと | プルリクエストのスコープ外とすること |
| 6 | 影響範囲 | ユーザーやメンバー、システムに影響すること |
| 7 | どうやるのか | 変更したものの使い方や再現手順 |
| 8 | 課題 | 悩んでいるところ、とくにレビューしてほしいところ |
| 9 | 備考 | - |
プルリクエストを出すときは、本文だけでなくタイトルづけも大切です。タイトルには、変更した内容が分かるように書きます。また、プルリクエストの本文は長ければいいというものでもありません。長い文章は読むコストを高めてしまうかもしれません。プルリクエストの前提が変わったときの保守コストもあります。シンプルにすることを心がけた方がいいと思います。
さらに、今ではなくあとから読むメンバーのためにも、プルリクエストの文章だけで前提知識が分かるようにすることも重要です。
プルリクエストのテンプレート
前述したプルリクエストの書き方をもとに、テンプレートをつくりました。人やチームによって書き方は変わってくると思いますが、なにかの参考になればうれしいです。
## 変更の概要 * 変更の概要 * 関連するIssueやプルリクエスト ## なぜこの変更をするのか * 変更をする理由 * 前提知識がなくても分かるようにする ## やったこと * [x] やったこと * [ ] やっていること ## 変更内容 * UIの変更ならスクリーンショット * APIの変更ならリクエストとレスポンス ## 影響範囲 * ユーザーに影響すること * メンバーに影響すること * システムに影響すること ## どうやるのか * 使い方 * 再現手順 ## 課題 * 悩んでいること * とくにレビューしてほしいところ ## 備考 * その他に伝えたいこと
まとめ
プルリクエストの本文は、プルリクエストの変更について把握するための文章です。読み手や、読み手の目的を想定した文章をつくるべきといえます。プルリクエストの本文を書くときは、テンプレートを利用することで、プルリクエストの作成コストを下げることができます。
