入門記事単語書籍

Gitのプルリクエストの書き方とテンプレート

私はふだんの開発でプルリクエストを出すとき、なんとなくフォーマット化したものを使っていました。プルリクエストについて整理するために、この記事でプルリクエストとはなんなのか、誰が読むのか、目的はなにか、書くべきことなどをまとめてみました。

記事の後半にはプルリクエストのテンプレートもありますので、よりよいプルリクエストにするための参考になればうれしいです。

プルリクエストの書き方とは

ここでいうプルリクエストの書き方とは、プルリクエストの本文についての書き方のことです。プルリクエストの本文は、ひとことで言うと『ファイルの変更について表した文章』といえます。

プルリクエストの本文には、一般的には変更の概要や変更点、再現手順などが書かれます。自由に書けますが、気をつけるべきポイントもあります。人それぞれ、チームそれぞれで書き方はあると思いますが、よりよくしたいときにこの記事が参考になればと思います。

この記事では、プルリクエストのコードについては言及していません。たとえば『変更の目的はひとつであるべき』や『差分を小さくすべき』といったことについては書いていません。

この記事で想定している読者

この記事は、Gitを用いて開発するエンジニアの方を想定して書いています。とくにチームで開発している方にとって有用だと思います。

プルリクエストと聞くとGitHubですが、Bitbucketなど他のプラットフォームを利用している方にとっても参考になると思います。

プルリクエストの書き方を気をつけるべき理由

プルリクエストの本文を書く上で気をつけるべき理由として、大きく次の3つがあると思っています。

  1. 読むコストを下げるため
  2. いいフィードバックをもらうため
  3. プルリクエストはドキュメントでもあるため

1. 読むコストを下げるため

プルリクエストのレビューは時間がかかりますし、頭も使います。レビュワーの方が内容をできるだけ早く、ラクに把握できると、プロダクトの価値向上など他のことに時間を使えるようになります。

コミュニケーションコストも減るので、早いレビューにもつながります。なかなかレビューされないと、コンフリクトが起きて自分がつらい目にあってしまうかもしれませんよね。

2. いいフィードバックをもらうため

プルリクエストの変更の内容が分かりやすかったり、とくに見てほしいポイントが明確だと、よりよいフィードバックにつながるかもしれません。

3. プルリクエストはドキュメントでもあるため

開発や運用のためのドキュメントと同じく、プルリクエストもドキュメントの一部です。

将来のメンバーがあるコードに関わるときに、関連するプルリクエストを見ることもあります。今プロダクトに関わっている人だけではなく、あとから読む人のことも想定した内容であるべきといえます。

プルリクエストは誰のために書くのか

プルリクエストの本文は、次の方を読者として想定しながら書くと、よいプルリクエストにつながります。

  • レビュワーのため
  • 自分のため
  • 将来のメンバーのため

レビュワーのために書く、というのは分かりやすい理由だと思います。自分のために書くと、プルリクエストに問題がないかを確認することができます。

また、前述したように将来のメンバーのためにも書きます。これはプルリクエストに前提知識がいらないように書く、などの気をつけるポイントにつながります。

プルリクエストの書き方

それでは、プルリクエストの本文になにを書くかについてまとめます。プルリクエストの本文には、次のような項目を書いていくといいと思っています。

順番見出し備考
1変更の概要概要、関連するIssueやプルリクエスト
2なぜこの変更をするのか-
3やったことチェックボックスで進捗を表す
4変更内容UIのスクリーンショット、APIのリクエスト/レスポンスなど
5やらないことプルリクエストのスコープ外とすること
6影響範囲ユーザやメンバー、システムに影響すること
7どうやるのか変更したものの使い方や再現手順
8課題悩んでいるところ、とくにレビューしてほしいところ
9備考-

プルリクエストを出すときは、本文だけでなくタイトルづけも大切です。タイトルには、変更した内容が分かるように書きます

また、プルリクエストの本文は長ければいいというものでもありません。長い文章は読むコストを高めてしまうかもしれません。プルリクエストの前提が変わったときの保守コストもあります。シンプルにすることを心がけた方がいいと思います。

また、今ではなくあとから読むメンバーのためにも、プルリクエストの文章だけで前提知識が分かるようにすることも大切です。

プルリクエストのテンプレート

前述したプルリクエストの書き方をもとに、テンプレートをつくりました。人やチームによって書き方は変わってくると思いますが、なにかの参考になればうれしいです。

## 変更の概要

* 変更の概要
* 関連するIssueやプルリクエスト

## なぜこの変更をするのか

* 変更をする理由
* 前提知識がなくても分かるようにする

## やったこと

* [x] やったこと
* [ ] やっていること

## 変更内容

* UIの変更ならスクリーンショット
* APIの変更ならリクエストとレスポンス

## 影響範囲

* ユーザに影響すること
* メンバーに影響すること
* システムに影響すること

## どうやるのか

* 使い方
* 再現手順

## 課題

* 悩んでいること
* とくにレビューしてほしいところ

## 備考

* その他に伝えたいこと

まとめ

プルリクエストの本文は、プルリクエストの変更について把握するための文章です。読み手や、読み手の目的を想定した文章をつくるべきといえます。

プルリクエストの本文を書くときは、テンプレートを利用することで、プルリクエストの作成コストを下げることができます。

参考文献

  1. レビューしてもらいやすいPRの書き方
  2. Pull Requestのフォーマットを決めるとレビューの効率が3倍よくなる

Webエンジニア&プロダクトマネージャ。 プログラミングで『ひとりで働く』を模索中。 三重の山の中で妻とこども、ネコとのんびり暮らしています。

Follow @zenizh
\ 記事をシェアしよう /

この記事を気に入っていただけましたら、ぜひフォロワーの方にシェアしてくださいね

ツイート画面をひらく
関連記事関連書籍
現場で使えるRuby on Rails 5

共著で『現場で使えるRuby on Rails 5(マイナビ出版)』を書きました。

Amazonでみる
© Product Development IO