プルリクエストを決めてチームで共有しておくことで、コードレビューを円滑に行なえるなど、様々なメリットがあります。 この記事では、フォーマットに書くべき項目や例などを紹介します。
なぜつくるのか
あらかじめプルリクエストのフォーマットを決めておくことで、以下のようなメリットがあります。
- フォーマットの内容を満たすようなプルリクエストになるため、自然とコードの品質が上がる
- レビュワーは事前にプルリクエスト本文の流れが分かるため、内容を理解しやすく、スムーズにレビュー作業に移行できる
- 書くべき内容が決まっているため、プルリクエスト作成に要する時間を短縮できる
書くべき項目
プルリクエストの本文には、以下の項目があればよいと思います。
- 変更の概要
- UIの変更点
- スクリーンショットやアニメーションなどで提示する
- 機能の使い方/バグの再現手順
- テスト項目
- ユニットテストではなく、テスト環境でレビュワーに確認してほしい項目
- 今回保留にしたToDo
- 備考
- 関連URL
- 参考にしたリソース
- チケット
もちろん、これ以外にもプロジェクト固有の項目もあると思います。 必要に応じて追加します。
フォーマット例
タイトル
プルリクエストのタイトルは、なにに対してどのような変更を加えるかが分かりやすいタイトルにします。
例：記事一覧のソート方法として「人気順」を追加する
本文
以下のように、コピー&ペーストやGitHubのテンプレート機能などで、すぐにプルリクエストを書けるよう、Markdown形式でフォーマットを準備します。
## 変更の概要
- 現状の問題点
- この変更が解決すること
- ...
## UIの変更点
- 変更前のUI
- 変更後のUI
## 機能の使い方/バグの再現手順
1. 変更した機能の使い方
2. バグであればその再現手順
3. ...
## テスト項目
- [ ] テスト環境でレビュワーに確認してほしいこと
- [ ] ...
- [ ] ...
## 今回保留にしたToDo
- [ ] 今回は保留にしたが、今後対応しなければならないこと
- [ ] 必要に応じてチケットやissueを発行する
- [ ] ...
## 備考
- レビュワーに対する注意点など
- ...
- ...
## 関連URL
- 参考にしたリソース
- チケット
- ...
つくったらどうするか
プルリクエストのフォーマットをつくったら、誰もがいつでも参照できるよう、チームのドキュメント共有サービス上などで共有します。
また、共有されたフォーマットにそってプルリクエストをつくることを必須とします。 具体的には「満たしていないプルリクエストはレビュー&マージしない」といった方針をとり、フォーマットに従うことを習慣化します。
形骸化は絶対に避けるべきなので、習慣化できないようであれば書くべき項目を減らすなど工夫してみましょう。
一度作成したフォーマットは、絶対ということはもちろんありません。 必要に応じてチームで議論し、随時更新していきましょう。
おわりに
プルリクエストの本文作成をしっかり運用できると、よいコードを維持できるきっかけになります。 まだフォーマットがなく、その必要性を感じた際は、導入を検討してみてはどうでしょうか。