こんにちは、ヒロケイです。
GitHubを使ってチーム開発をしていると、プルリクエストを作成する場合が出てきますよね。そんな時
- プルリクの説明に何を書けば良いか分からない
- 毎回同じような構成で書きたいけど、ある程度自動で作成する方法はないだろうか?
GitHubって機能がいっぱいあってどこから手をつけて良い迷いますよね💦
今回は、GitHubのプルリクにテンプレートを作成する方法についてまとめました。
- プルリクには何を書けば良いのか分かる
- 説明の構成をテンプレートで設定し、プルリクを生成した時点で自動生成できるようになる
- チームで役立つプルリクを作れるようになる
それでは、やっていきましょう!
/.github/PULL_REQUEST_TEMLATE.mdを作成します。
mkdir .github
touch .github/PULL_REQUEST_TEMPLATE.md
おすすめのテンプレートがあるので、こちらをファイルにコピペしましょう!
## チケットへのリンク
## やったこと
## やらないこと
## できるようになること(ユーザ目線)
## できなくなること(ユーザ目線)
## 特にレビューして欲しい箇所
## 動作確認
## その他
プルリクを作成する際に重要になってくる内容をまとめています。
もちろん、タスクやチケット内容によっては全て書く必要がない場合も出てきます。
その場合は書かなくても大丈夫!
テンプレートの設置はできたけど、どうして説明を書く必要があるんだろう?
プルリクに説明を書く理由は、主に3つあるよ!
チーム開発において、プルリクに的確な説明を書くことはとても重要になってきます。
その理由や目的について見ていきましょう!
まず、コードレビューする人のために書くのです!
説明に何も書いてない状態でレビューを依頼するのは、なんの説明もせずに仕事をお願いしているのと同じことになります。
一方、プルリクに
- どんなところを見て欲しい
- 結果的にどんな動きになっています
といった内容が説明にあると、レビューの方向性がグッと上がります。
結果的に良いフィードバックをもらえるわけですね✨
もちろん、説明はレビュワーのためのものだけではありません。
半年後、1年後の自分かもしれません。
後々コードリーディングやデバッグなどをする際、差分を辿っていくとプルリクを見ることがあります。
そんなときにプルリクの説明があると差分の詳細を一目で確認できるため、説明は丁寧に作成しておく必要があるでしょう。
説明は、変更点の詳細を言語化していく作業になります。
なので、説明を書くのはコードの差分と期待する動作に齟齬がないかを確認する作業にもなります。
一つのプルリクは1つの目的に絞りましょう!
例えば
- バグ修正のプルリクだったはずが、周辺コードのリファクタリングもしてしまっている
- 機能追加のはずが、他のタスクのバグ修正も一緒にやってしまっている
このような差分はレビュワーに優しくないです。
レビュワーは基本的に差分が小さいほどレビューしやすいです。
差分が少ないと、レビューする量が少なく済むのでね(^^)
なので、差分の量を増やさないためにも、1プルリク1目的を意識しましょう!
1つの大きなプルリクより5つの小さなプルリクを出せる人の方が、チーム開発では重宝されるでしょう!
差分のファイル数は10以下にとどめておくようにしましょう!
これもレビュワーがみる量を減らしておく目的があります。
プルリクを見にくる人は、差分についての前提条件を理解していない人もいます。
そんな方にもわかるよう、前提知識が必要ない説明を書きましょう!
他人だけでなく、半年後、1年後の自分が見る可能性もあります。そうなった時に内容を把握できるような説明をかけると良いですね!
個人的にはすごく良いと思いました。
優秀な人は、”読む”よりも、”見て”理解できる説明を書くそうです。
期待する挙動などを動画に収めておくと、レビュワーが動作確認をする際にとても役立ちます。
Macだと
- shift + command + 3: 画面全体のスクショ
- shift + command + 4: 範囲指定のスクショ
- shift + command + 5: 画面録画(範囲指定)
でできるので、ぜひやって見てください!