はじめに
現在所属しているオンラインサロンにてRailsアプリの共同開発を行うことになりました。
私自身、共同開発は初めての経験のため、人生で初めてコードレビューを行うことになります。
そこで、この貴重なコードレビューの機会をより有意義なものにしたいと思い、共同開発を始める前に「共同開発をする際のGitコミュニケーション」についてまとめてみようと思います。
今回まとめるのは以下の３点です。
✅ コミットメッセージ
✅ プルリクエスト
✅ コードレビュー
また、共同開発終了後には今回まとめたコミュニケーションにてPDCAを回した結果をまとめていきたいと思います。
この記事のターゲット
- Gitを使って開発を行っている方
- 共同開発初心者の方
- 丁寧なGitコミュニケーションを実現したい方
レビュイーのコミュニケーション
GitHubなどを使用して共同開発を行っていく際は、メンバー間でコードレビューを行うことが多いと思います。
その際に、非常にわかりづらいプルリクエスト（以下'PR'）やコミットメッセージが残されていたら、レビュアーにアサインされた人はどう思うでしょうか？
気遣いができない人だなと思われるなど、少なからずマイナスな印象を持たれてしまうでしょう。
そこで今回はそのような事態を未然に防ぐために、コードレビューを依頼する立場としてどのようなコミットメッセージやPRを残すべきか考えていきたいと思います。
コミットメッセージ
概要
[コミット種別選択] 変更内容の一行説明
変更した理由を具体的に説明
以下にて各ポイントを説明します。
ポイント解説
① コミット種別をつける
何をしたか接頭辞で短く表現します。
コミット種別をつけることでどのような視点で該当のコミットメッセージを確認すればいいのか一目でわかるようになるでしょう。
以下に、コミット種別の例をまとめました。
多すぎても管理できないと思うので、ひとまず使いそうだなと思ったものをまとめました。
PDCAを回していく中で、必要なもの不要なものがあれば更新していきます。
【コミット種別】
fix：バグ修正
add：新規（ファイル）機能追加
update：機能修正
remove：削除（ファイル）
clean：リファクタリング
test:テスト
move：AをBに移動
② 変更内容を一行で説明する
変更した内容を一行にまとめます。
一行にまとまるサイズ感でコミットすることを意識することで、コミットが大きすぎず小さすぎずまとまりが良くなるのではと考えています。
③ 変更した理由を説明する
変更した理由を記述します。
理由を書くことで、レビュイーの意図がレビュアーに伝わりやすくなるため良質なコミュニケションを取れるのではと考えます。
プルリクエスト
概要
# 変更の目的
〇〇できるようにするため
# 達成条件
- [ ] 条件①
※できればキャプチャ画像か動画を添付する
- [ ] 条件②
※できればキャプチャ画像か動画を添付する
- [ ] 条件③
※できればキャプチャ画像か動画を添付する
- [ ] 条件④
※できればキャプチャ画像か動画を添付する
# 条件達成のために行った変更の内容
- [ ] 変更内容
>[update][add][remove][fix]から選択 変更ファイル名を記載
- [ ] 変更内容
>[update][add][remove][fix]から選択 変更ファイル名を記載
# 関連Issue
#○←関連Issue番号を記載
# レビュー完了希望日
レビュー完了希望日時は以下の通りです。
・2020年○月○日(○曜日)〇〇:〇〇まで
お忙しい中恐れ入りますが、何卒よろしくお願いいたします🙇♂️
※PR作成の際には画像右上の
Reviewersにコードレビューしていただきたい人をアサインし、その下のAssigneesにPR作成者（自分）を忘れずにアサインしましょう。
ポイント解説
① 題名はIssueに合わせる
題名は極力Issueに合わせるようにします。
関連Issueのリンクも貼り付けますが、一目でどのIssueを課題を解決する変更なのか認識できるようにするためです。
② 変更の目的を説明する
なぜこの変更を行うのか、変更の目的や変更の背景を説明します。
変更の目的を共有しておかなければ、レビュイーの意図に反したレビューを行うことになってしまうと考えるからです。
例)「ユーザが掲示板を投稿できるようにするため」など
③ 達成条件を説明する
上記の目的を達成するための条件を説明します。
レビュアーがコードを把握する上で、正しい挙動はどのようなものかを理解しておく必要があるためです。
例)「投稿内容が必須になっている」
「エラーメッセージが日本語で表示されるようになっている」
「投稿内容は140文字以内に制限されている」など
④ 条件達成のために行った変更の内容を記載する
上記の条件達成のためにどのような変更を行なったのか、またどのファイルが関連しているのかを記載します。
変更内容とその変更に伴って編集したファイルの情報を共有しておかないとコンフリクトが起こってしまう可能性があるためです。
例)modelのvalidationを設定
[update] app/models/post.rb投稿フォームを作成
[add] app/views/posts/new.html.haml
[remove] app/views/templates/new.html.haml
⑤ 関連Issueのリンクを添付する
どのIssueの課題を解決する変更であるかを明示します。
リンクを貼り付けておくことでレビュアーの負担を減らしてあげることができるので良質なコミュニケーションになるのではと考えます。
ちなみにCloses#<関連するIssue番号>と書くと、PRがmergeされたタイミングで、関連Issueも閉じてくれるそうです。
例) 関連Issue ⇨ #1
⑥ レビュー完了希望日を記載する
レビュー完了希望日も記載すべきだと考えます。今回の共同開発は、完成目標が２週間であり、またクリスマスや年末年始など多くのイベントを挟むため、しっかりとしたスケジュール管理が必要であると考えるからです。
実際の業務でも期限を設定しなければ仕事の優先順位を決めることはできないので、期限の設定は重要であると考えます。
例)レビュー完了希望日時は以下の通りです。
・2020年12月25日(金)21:00まで
お忙しい中恐れ入りますが、何卒よろしくお願いいたします🙇♂️
⑦ キャプチャ画像／動画を添付する
実際にRevieweeのローカル環境では動作確認ができていることを担保するために、キャプチャ画像や動画を掲載するのが親切であると考えます。
しっかりと動作することが前提のレビューの方がReviewerの負担が軽くなると考えるからです。
レビュアーのコミュニケーション
次にコードレビューの書き方についてです。
PRにてレビュアーにアサインされたメンバーはコードレビューを行うことになります。
今回は、自分自身含めてメンバーみな共同開発未経験者ということで、コードレビューの場を「意見する場」ではなく、「知識を共有する場」、「コミュニケーションを学ぶ場」として活用するのが適切ではないかと考えています。
そこで今回は「知識共有」という観点でコードレビューのポイントを洗い出したいと思います。
コードレビュー
概要
修正希望がある場合のレビューテンプレート
### 修正希望
[MUST][IMO][NITS]から適切なものを選択
[修正内容／気になる部分など]
### 理由
[上記修正を希望する理由]
### 提案
[自分が考える修正案]
質問がある場合のレビューテンプレート
### 質問内容
[Q] [質問内容を記述]
### 理由
[質問理由を記述]
ポイントの解説
① 修正希望には理由と修正案を添える
修正希望を出す際には、修正希望だけではなく理由を添えます。ロジックを用いて相手が納得できるように伝えることで、双方納得して作業を進められると考えるからです。
また、修正案とその理由も伝えると知識を共有でき前向きなレビューになると考えます。
② 修正希望には[MUST]など項目をつけて、その修正の重要度を明示する
修正を希望する場合は、その修正がどれくらい重要なものかを明示してあげることで良質なコミュニケーションになると考えます。
項目には以下のようなものが考えられます。
[MUST] 絶対に修正して欲しいときにつけます。
[IMO] 「自分ならこうする！」や「自分はこう思うのだけどどう思いますか？」などの意見があるときにつけます。(In my opinionの略)
[NITS] 細かい指摘や、軽い修正をして欲しいときにつけます。
（例）インデントを揃えて欲しいです！
[IMO]は知識の共有という観点でも積極的に使っていけたらいいなと思います。
それぞれ重要度によって使い分けてみましょう。
③ わからない点があれば積極的に質問する
わからない点があれば、積極的に質問しましょう。
聞く側にとってはナレッジ共有の場として、教える側にとってはアウトプットの場として有意義であると考えます。
また、質問がある際には以下のように項目づけを行うと良質なコミュニケーションになるでしょう。
[Q] 質問がある場合につけます。
（参考）コードレビューの流れ
コードレビューの流れをまとめます。
① コードを確認する
レビュアーにアサインされた人はGitHubの［Pull Requestsタブ］の［Files Changed］でコードを確認します。
② レビューコメントを書く
コードの修正希望やコードの不明点があった場合は、対象の行を選択してコメントを残し［Start a review］を押します。
③ フィードバックを送信する
コードのレビューが終わり、コメントの記入が完了したら、画面右上にある［Finish your review］を押します。
この際、フィードバックの種類は以下３つから選択できるので状況に応じて使い分けます。
Comment
コメントを残す際に使用します。
項目でいうと[NITS]や[IMO]や[Q]の場合に使用します。（後述）
また「コード読みやすいですね！」や「こんな書き方もあるんですね！勉強なりました！」など褒め合うことができたら最高です！Approve
コメントを残した上で、PRの承認まで行います。
基本的には、修正箇所がなくLGTMを出す際に利用すればいいと思います！Request changes
コードの修正依頼をする際に使用します。
項目でいうと[MUST]の時に使用します。（後述）
この際、修正して欲しい理由や自分なりの提案とその理由まで記述できればかなり素敵だなと思います。
フィードバックの種類を選択し終えたら［Submit review］を押し、レビューを反映させます。
無事レビューが完了したら［Conversationタブ］にレビューの内容が反映されます。
④ レビューの内容をもとにローカル環境で修正する
レビュイーはレビューしてもらった内容をもとにローカル環境で修正を行いましょう。
⑤ 修正が完了したら、対象ブランチをpushする
修正が完了したら、リモートにpushします。
この際に、［Conversation］のレビューに修正が完了した旨を伝えます。
⑥ Reviewerが修正内容を確認する
レビュアーは［Files Changed］でコードの修正内容を確認し、OKであれば［Conversation］にてLGTMを出します。
また［Resolve conversation］を押し、対象の修正内容がcloseしたことを明示しましょう。
⑦ masterにmergeする
レビュイーは全てのメンバーのLGTMをもらうことができたらリモートのmasterにmergeします。
mergeか完了したら共同開発メンバーは各自リモート環境のmasterブランチにpullを行います。
以上がコードレビューの大まかな流れです。
上記作業を繰り返して機能実装を行なっていきます。