Zenn
💬

【GitHub】プルリクエストのテンプレートを設定しておこう！ポイントも解説

2024/09/03に公開
GitHub
Pull Request
開発管理
tech

こんにちは、ヒロケイです。

GitHub を使ってチーム開発をしていると、プルリクエストを作成する場合が出てきますよね。そんな時

  • プルリクの説明に何を書けば良いか分からない

  • 毎回同じような構成で書きたいけど、ある程度自動で作成する方法はないだろうか？

GitHub って機能がいっぱいあってどこから手をつけて良い迷いますよね 💦

今回は、GitHub のプルリクにテンプレートを作成する方法についてまとめました。

この記事を読むことで

  • プルリクには何を書けば良いのか分かる

  • 説明の構成をテンプレートで設定し、プルリクを生成した時点で自動生成できるようになる

  • チームで役立つプルリクを作れるようになる

それでは、やっていきましょう！

プルリクのテンプレート　設定方法

プロジェクトのルートディレクトリにてファイルを作成

/.github/PULL_REQUEST_TEMLATE.md を作成します。

mkdir .github
touch .github/PULL_REQUEST_TEMPLATE.md

テンプレート

おすすめのテンプレートがあるので、こちらをファイルにコピペしましょう！

## チケットへのリンク


## やったこと


## やらないこと


## できるようになること（ユーザ目線）


## できなくなること（ユーザ目線）


## 特にレビューして欲しい箇所


## 動作確認


## その他

プルリクを作成する際に重要になってくる内容をまとめています。

もちろん、タスクやチケット内容によっては全て書く必要がない場合も出てきます。

その場合は書かなくても大丈夫！

プルリクの説明は何のために書くのか？

テンプレートの設置はできたけど、どうして説明を書く必要があるんだろう？

プルリクに説明を書く理由は、主に 3 つあるよ！

チーム開発において、プルリクに的確な説明を書くことはとても重要になってきます。

その理由や目的について見ていきましょう！

レビュワーが良いフィードバックを送るため

まず、コードレビューする人のために書くのです！

説明に何も書いてない状態でレビューを依頼するのは、なんの説明もせずに仕事をお願いしているのと同じことになります。

一方、プルリクに

  • どんなところを見て欲しい

  • 結果的にどんな動きになっています

といった内容が説明にあると、レビューの方向性がグッと上がります。

結果的に良いフィードバックをもらえるわけですね ✨

将来のドキュメントにもなるため

もちろん、説明はレビュワーのためのものだけではありません。

半年後、1 年後の自分かもしれません。

後々コードリーディングやデバッグなどをする際、差分を辿っていくとプルリクを見ることがあります。

そんなときにプルリクの説明があると差分の詳細を一目で確認できるため、説明は丁寧に作成しておく必要があるでしょう。

コードの差分と目的が一致しているか自己レビューするため

説明は、変更点の詳細を言語化していく作業になります。

なので、説明を書くのはコードの差分と期待する動作に齟齬がないかを確認する作業にもなります。

こんなことを意識すると良いプルリクが作れるよ 4 選

プルリクには目的を 1 つに絞るべし

一つのプルリクは 1 つの目的に絞りましょう！

例えば

  • バグ修正のプルリクだったはずが、周辺コードのリファクタリングもしてしまっている

  • 機能追加のはずが、他のタスクのバグ修正も一緒にやってしまっている

このような差分はレビュワーに優しくないです。

レビュワーは基本的に差分が小さいほどレビューしやすいです。

差分が少ないと、レビューする量が少なく済むのでね(^^)

なので、差分の量を増やさないためにも、1 プルリク 1 目的を意識しましょう！

1 つの大きなプルリクより 5 つの小さなプルリクを出せる人の方が、チーム開発では重宝されるでしょう！

差分ファイル数は 10 以下にするべし

差分のファイル数は 10 以下にとどめておくようにしましょう！

これもレビュワーがみる量を減らしておく目的があります。

前提知識がいらない説明を書くべし

プルリクを見にくる人は、差分についての前提条件を理解していない人もいます。

そんな方にもわかるよう、前提知識が必要ない説明を書きましょう！

他人だけでなく、半年後、1 年後の自分が見る可能性もあります。そうなった時に内容を把握できるような説明をかけると良いですね！

期待する挙動はスクショや録画をして載せておくべし

個人的にはすごく良いと思いました。

優秀な人は、"読む"よりも、"見て"理解できる説明を書くそうです。

期待する挙動などを動画に収めておくと、レビュワーが動作確認をする際にとても役立ちます。

Mac だと

  • shift + command + 3: 画面全体のスクショ

  • shift + command + 4: 範囲指定のスクショ

  • shift + command + 5: 画面録画(範囲指定)

でできるので、ぜひやって見てください！

Discussion