
この記事では、「GitHub上でPull Request(プルリクエスト)を出すときに、どういう書き方・フォーマットで出せば良いのか」について書いています!
Pull Requestと記載しましたが、GitLabでいうところのMerge Requestでも内容としては変わりありません。
Pull Requestの書き方に関しては、テンプレートを設けて内容を記載している方が多いかと思いますが、下記のような方に向けて、この記事を書きました。
- Pull Requestのテンプレートを設けていない
- これからPull Requestのテンプレートを作ろうと思っているけれど、どういう項目や内容を書いたら良いか悩んでいる
Pull Request(プルリクエスト)の書き方に気をつけるべき理由

PRの書き方に気をつけるべき理由としては、大きく分けて下記の3つがあると思っています!
- レビュワーの負担を減らすため
- 変更内容を後からでも確認しやすくするため
- 適切なフィードバックをもらうため
レビュワーの負担を減らすため
個人開発など1人で開発する場合は、そこまでPRの書き方に気をつける必要はないと思いますが、チームで開発をする場合、基本的にはレビュワーがいます。

仮に自分がレビュワーの立場で、全く説明が書いていないPRを投げられたらどうでしょうか?
その場合、
- 実装した背景・理由
- 要件が適切に実装されているか
といったことが分かりません。チャットで上記のことを送っていたとしても、後からPRを確認する場合非常に手間がかかります。
なので、レビュワー側の負担を減らす・時間を奪わないためにも、PRに実装の背景は記載するなど書き方・書く項目には気をつけるべきです。
変更内容を後からでも確認しやすくするため
基本的には、「PRを作成 → レビュワーにレビューしてもらい、OKをもらう → マージする」といった流れになるかと思います。
マージした後に、他のメンバーが加わり、過去の履歴を確認する場合もあります。
そういった場合に、マージしたPRに説明が記載されていなかったり、雑に書かれていたりすると、過去の変更内容を追うのに苦労します。

なので、PRも1ドキュメントと考えて記載すると、変更内容を後からでも確認しやすくなります!
適切なフィードバックをもらうため
PRを出したものの、若干書き方や実装方法に不安がある場合があるかと思います。
そういったときに、どういうところに不安があるか・どういうところを特に見てほしいかといったことを書いておくと、自分が期待するフィードバックをもらえる可能性が高くなります。
Pull Request(プルリクエスト)の書き方
それでは、どのような項目や内容をPRに書くと良いかについてまとめていきます。
Pull Request(プルリクエスト)に記載すると良い項目・内容
# 対応したチケットやIssueのURL
対応タスクに関して、JiraやBacklogまたはIssueで管理している場合は、該当するURLを記載しておきます。
対応したチケットやIssueには実装背景や理由・要件等が書いてあります。
# 実装内容
何を実装したのかを箇条書きで記載しておきます。
実装内容を記載することで、実装漏れしている箇所がないか、レビュワー側で簡単に確認することができます。
実装内容を概要だけでも良いので、全てここに記載するという運用にすれば、要件に記載されている内容が実装されていない場合、レビュワーはすぐに依頼元へ返すことができ、レビュワーの負担が減ります。
UIの実装がある場合はスクリーンショットや動画、APIの実装がある場合はリクエストとレスポンスを記載します。
# 補足
実装方法が複雑な箇所や、どういった考えで実装したのか補足した方が良いなと思う内容をここに書きます。
# 特に確認してほしい部分
実装した中で、特に確認してほしい部分を記載します。
例えば「こういう実装をしたけど、自信がないので特に確認してほしい」など。
# 動作確認
動作確認方法や結果を書きます。

PRには、上記のような項目・内容を記載すると良いと思っています!
Pull Request(プルリクエスト)のテンプレートをリポジトリ単位・アカウント単位で適用する方法
GitHubのリポジトリにPRフォーマットを適用したい場合は、以下の手順を実施します。
- PRのテンプレートを適用したいリポジトリに「.github」ディレクトリを作成する
- 「.github」ディレクトリ配下に「PULL_REQUEST_TEMPLATE.md」ファイルを作成し、テンプレートを記載する
リポジトリ単位ではなく、アカウント単位でPRのテンプレートを適用したい場合は、以下のように「.github」リポジトリを用意してあげます。
- 「.github」というpublicリポジトリを作成する
- 「.github」リポジトリのルート、または「docs」や「.github」ディレクトリ配下に「PULL_REQUEST_TEMPLATE.md」ファイルを作成し、テンプレートを記載する

「PULL_REQUEST_TEMPLATE.md」ファイルと記載しましたが、公式ドキュメントには、PRのファイル名は大文字と小文字が区別されないと記載されているので、小文字でも問題ないです!
公式ドキュメント:Issueとプルリクエストのテンプレートについて
まとめ|Pull Request(プルリクエスト)の書き方
ここまで、「Pull Request(プルリクエスト)の書き方」について紹介してきました。
レビューしやすいPRを出すことにより、レビュワー側の負担も軽減され、コードの品質も上がります。

紹介してきたPRの書き方に関しては、あくまで1つの例なので、開発チームに合わせてPRの項目は変更したり、定期的にフォーマットの見直しを行うと良いかと思います!
コメント