テンプレートを使って、より良い情報が入った&レビューしやすいプルリクを

GitHubでは「プルリクエスト」という機能を使ってコードのレビューやマージを行うことができます。プルリクエストを作るときには本文にプルリクエストについての説明を書くことができますが、デフォルトでは真っさらで自由に記述することができます。テンプレートを設定することで、プルリクエスト作成時に、雛形となる文章を表示できます。
本記事では、テンプレートの設定方法、私自身がチームで使っているテンプレートの紹介を行いたいと思います。特に後者は一案として参考になればと思います。

テンプレートの設定方法

テンプレートを設定したいリポジトリに pull_request_template.md という名前でテンプレートを作成します。 pull_request_template.mdファイルの置き場は以下のうちのどこかである必要があります。

• リポジトリルート/pull_request_template.md
• リポジトリルート/docs/pull_request_template.md
• リポジトリルート/.github/pull_request_template.md

以下、テンプレートの例です。

pull_request_template.md

# 説明
<!-- このプルリクエストの説明を書いてください -->

# 確認したこと
<!-- 動作確認した内容を書いてください -->

上記テンプレートをリポジトリに追加し、デフォルトブランチにマージすると、プルリクエストを作る際に以下のように反映されます。

ハマりポイント

• テンプレートファイルの置き場所に気を付けましょう
• テンプレートはデフォルトブランチにマージされると適応されます

参考

テンプレート案

ここでは現在私が入っているチームのテンプレートについてご紹介させていただきます。
(内容についてはそのまんまコピーしてきたものではなく、適宜修正を入れております。)

テンプレートに含めている内容は以下の通りです。

• チケット番号
• このプルリクエストがマージされると、何が変わるのか
• レビューして欲しい観点
• 確認したこと
• プルリクエスト作成時のチェックリスト
• コメントする方へ

一つずつ説明します。

チケット番号

このプルリクエストが生まれた元になっているチケットの番号を書きます。私のチームではタスクをチケットで管理しているのでチケット番号となっていますが、タスク番号、課題番号などと同意です。
GitHubには外部リソースを参照して、自動的にリンクを作ってくれる機能があります。例えば、TASK-10 という文字列を書いたときに、https://xxxx.xxx.xxx/task?query=TASK-10へのリンクを自動的に貼る、といったことができます。設定しておくと、プルリクエストにチケット番号を書くだけで実際のチケットに飛べるようになるのでとても便利です。
詳しくは外部リソースを参照する自動リンクの構成をご覧ください。

このプルリクエストがマージされると、何が変わるのか

プルリクエストの概要をレビュアーに説明します。どんな変更を加えたのか、その結果どうなるのか、などを書きます。画面変更の場合はここにbefore/afterのスクショを貼ったりもします。

レビューして欲しい観点

レビュアーに特段レビューして欲しい点があれば書きます。例えば、この変数名もっといいものがないかな、とか、ここの設計迷ったけどどうでしょう？、などです。

確認したこと

動作確認した内容を書いています。フォーマットやどこまで詳しく書くのかは決めていません。プルリク作成者(実装者)がここに書くことによって、そういえばここの観点は確認していなかった、など漏れに気づく効果を狙っています。

プルリクエスト作成時のチェックリスト

ここにはチェックリストを載せています。チェックリストの内容もテンプレートにしています。特定の変更がある場合にテストすること、や、このファイルに変更があったらこっちも確かめること、のような毎回やらなくてもいいけど場合によっては必要、といったことがチェックリストになっています。レビュアーはここに全てチェックが入っていることを確認します。

チェックリストの内容は時々変わります。これはもうチェックしなくても染み付いてきたよね、となれば削除しますし、新たなものが生まれたら追加しています。チェックリストが多すぎても形骸化してしまうので、私のチームでは大体3つ以下にしています。それ以上になった場合は改めて中身を見直したり別のところ(プルリク時以外やCIでチェックなど)でチェックできないかを考えて、移動したりしています。

コメントする方へ

レビュアーに忘れないで欲しいことを書いています。現在は、優先度を表現しましょう、といったことを書いています。
https://qiita.com/kuniyonkunisan/items/2ed8c48ff349e6add45b を参考にさせていただいています。

テンプレートは定期的に見直しを

上でも何度か書いていますが、テンプレートは定期的に見直し、そのとき必要な情報が含まれるようにすると良いと思います。私のチームでは、普段開発していて気づいたときに修正するといったこともありますが、振り返りでTry事項が生まれた際にプルリク時にチェックしよう、ということで結果テンプレート見直しの機会になる、ということが多いです。

また、私のチームでも最初からここまでのテンプレートを作っていたわけではありません。日々活動を重ねる中でちょっとずつ進化させてきましたし、これからも進化していくと思います。初めてやる場合には必要最低限で初めて、チームの状況に合わせてちょっとずつ項目を増やすなり減らすなりしていくことをお勧めします。

最後に

プルリクエストのテンプレートを使うことで、良い情報が詰まったプルリクエストを作ることができると思います。その結果、忘れ物(テストし忘れなど)が減ったり、レビュアーがレビューしやすいという効果も狙えます。テンプレートの内容はあくまで一案です。それぞれのチームにあった内容を考えてみてください。