こんにちは。rendaman0215です。
GitHubでレビュー時、PRに記載されている変更内容の粒度がレビュイによって異なりますよね。
そこで記載する内容や粒度を合わせるためにPRテンプレートを導入されているチームも多いと思います。
私のチームでもPRテンプレートを導入し始めたため、導入するまでの流れをまとめました。
テンプレートの構成を考える
まず、テンプレートの構成を考えるにあたり、直感的にほしいと思う項目、一般的な項目、別のチームで採用されている項目をまとめました。
- 関連するissue番号
- 修正内容
- レビューしてほしいポイント
- PR前のチェックリスト
- 参考資料
- 補足・その他
ここから一項目ずつ精査していき要否を検証していきました。
issue番号
私のチームでは、issueをチケットとして利用し、issue駆動で開発を行っており、PRには必ずissueが紐づくようになっているため、issue番号はマストでした。
GitHubでは、- {issueのURL}とPRに記述することで、issue番号＋issueのタイトルが表示されます。
しかし残念ながらGHEではissueのタイトルが表示されません。
弊社ではGHEを採用しているため、issue番号 + 概要を記載することとし、まとめて概要として採用することとしました。
修正内容
どこをなぜ どう直したか 修正した結果どうなるかを箇条書きでかく場所です。
概要より細かい粒度で書くことでレビュアの労力を軽減しています。
レビュアの想定外の場所が修正されていた際、その理由などきく必要がないためここの手間が省けます。
レビューしてほしいポイント
上記の内容を踏まえ、重点的にレビューしてほしいポイントや自信のないポイントを記載してもらいます。
こちらは、レビュイ視点で取り入れるべきと判断しました。
PR前のチェックリスト
別のチームで採用されているため、候補にあがりました。
そちらのチームでは、テストの実装ができているか、commit履歴にissue番号が入っているか、などのチェックリストがありました。
しかし、チェックリスト自体組織が大きくなっていくと形骸化しやすいこと、私自身チェックリストが苦手ということもあり、チェックリストは自動化することで廃止することとしました。
- ex)
- commit履歴の精査は、.precommitを利用し検証
- テストの実装は、カバレッジを出力することで対応
参考資料
ほとんど使われることがないため、補足・その他と一緒にまとめることにした。
PRテンプレート
上記の内容を踏まえ、最終的に出来上がったのが以下のテンプレートです。
## 概要
## 修正内容
## 影響範囲
## レビュー観点
## 補足
テンプレートの設定
公式ドキュメントで紹介されていますが、簡単にまとめると以下の通りになります。
- pull_request_template.mdというファイルを作成する
- PRテンプレートファイルは、基本的に
/.githubディレクトリに格納するとよい - デフォルトブランチにPRテンプレートファイルがcommit/mergeされると反映される
おわりに
PRテンプレートを用いることで様々なメリットがありました。
レビュアは以前よりレビューしやすく、レビュイはフォーマットを気にせずPRを作れるようになり、新規参入者は過去PRを見やすくなりました。
定期的に見直すことでよりよくしていきたいと思います。（遊び心で絵文字を追加するとか）