GitHubを使ったコードレビュー時のコメントの追加と返信のやり方が曖昧だったのでまとめました。
セルフレビュー時にコメントで補足情報を追加する
レビュワーに良いアドバイスをもらうためにセルフレビュー時に補足情報をコメントすることでレビュワーに意図や不明点を伝えます。
GitHub – Pull Requestをレビュー【コメントの書き方と修正依頼】 | Howpon[ハウポン]
1. インラインコメントの追加
コード内に補足情報をインラインで追加します。
File changed
内でコード横の+
をクリックしてコメントを記入- コメントを記入後、
Start a review
かadd single comment
を選択
Start a review
: 複数のコメントをまとめて反映する(Finish your review
でレビュワーに通知が飛ぶ)Add single comment
: コメント毎に反映する(コメント毎にレビュワーに通知が飛ぶ)
インラインコメントを終了するには次の手順であるFinish your review
のクリックが必要です。
2. レビューコメントの追加
レビュー自体のコメントを追加します。 コメントの内容としては「レビューお願いします。」みたいな感じで良いと思います。
File changed
内のFinish your review
をクリックし、レビューに対するコメントを追加- 次の3つからコメントの種類を選択
Submit your review
をクリックしてレビューコメントを反映
コメントの種類は次のようになっています。
Comment
: 通常のフィードバック、Mergeの許可には影響しないApprove
: 問題が無い場合のコメント、Mergeの許可するRequest changes
: 修正依頼、Mergeを許可しない
レビュー後のコード修正とコメントへの返信
レビュー後にレビュワーから何らかのコメントをもらうと思います。 コメントを元にレビュイー(レビューイ)はコードを修正し、コメントへ返信や質問をする事で疑問点などを解消します。
1. コード修正
1つの指摘に対して1コミットでコードを修正するとレビュワーが修正点を追いやすくなります。
2. コメントへの返信
コメントに返信することでレビュワーに対してコメントをチェックしていることを明確に伝えることができるので修正漏れを防止できます。
- コメントの返信は
Reply
からスレッドで返信する。 - インラインコメントは該当行を削除すると
File changed
で非表示になる。 - 非表示になったコメントは
File changed
内のConverstions
から返信する。 - コード修正後のコメント内に修正コミットIDを追加することでレビュワーが修正点を追いやすくなる。(
コメント <commitのリンク>
)
3. 再提出
File changes
内のReview changes
から修正したことをコメントする。
コメント内容は「修正したので再度レビューをお願いします。」みたいな感じで良いと思います。
Outdated、Pendingとは?
コメントの状態を示すものです。
Pending
コメントが保留の状態です。
コメント記入後のStart a review
からコメント終了時のFinish your review
までの間はPending
の状態になります。
Pending
状態のコメントは自分にしか見えないようになっているようです。
コメントした箇所に「Pending」と表示されます.この時点では該当箇所にコメントしたことはレビューイの画面に表示されません。コメントしたレビュアーにのみ表示されます。
プルリクエストでの「Start a review」と「Add single comment」の使い分けがよくわかってなかったのでまとめてみた - Beeeat’s log
Outdated
コメントが後続のcommitによって変更された状態です。
開発の方針によっては指摘点が解決した場合に後述するResolve conversation
ボタンを押すこともあるようです。
モダンなPull Requestの回し方 || log.pocka.io
Resolve conversation、Unresolve conversationとは?
Conversation
内に表示されるのコメントの内容が解決/未解決なのか示す機能です。
Resolve conversation
、Unresolve conversation
をクリックすることでコメントの表示/非表示を切り替えることができます。
Resolve conversation
コメントの内容が解決したら押すことで解決したことを明確にします。
クリックすることで表示が折りたたまれます。
Show resolved
をクリックすると折りたたみが解除されます。
Unresolve conversation
Resolve conversation
で非表示になったコメントを表示させます(未解決に戻す)。
誰がResolve conversationをクリックするのか?
次のようにプロジェクトのルール等によってResolve conversationをクリックの運用方法が異なるようです。
レビュイー/レビュアー両方のためにもちゃんと押してあげると、情報ノイズが減りやりとりの効率があがります。 なお、どちらが押すかについてはプロジェクト内で決めたほうがよさそうです。
モダンなPull Requestの回し方 || log.pocka.io
私は「レビュアー」が「Resolve conversation」ボタンを押すのが良いと思います。
レビュアーはリプライとコード修正を確認して問題なければ、conversation を resolve する
GitHub における PR レビュープロセス - conversation の活用 | 豆蔵デベロッパーサイト
あらかじめチームやプロジェクトのルールを確認しておいた方が良さそうです。
Viewed
File changed
内に表示されるセルフレビュー時に自分でチェックしたファイルのViewed
にチェックを入れて修正の進捗を表示する機能。
- チェックを入れたファイルは折りたたまれて表示される。
- レビュワーには影響しない。
- 進捗バーでチェック数が表示される。
積極的に使うことでセルフレビューの効率アップと修正漏れ対策になりそうです。
PR作成からマージまでの流れ
今回はコメントの追加や返信の部分のみ調べましたが、PR作成からマージまでの全体の流れはこちらの記事が非常に参考になりました。マージまでの全体の流れを確認しておくと理解しやすいかもしれません。
[GitHub]最低限、これだけは知っておきたいプルリクエスト | Unity Indies
感想
コードレビュー時のコメントの返信について曖昧な部分が多かったけど少しは理解できたので良かった。 GitHubには便利な機能がたくさんあるので少しづつ理解して覚えていきたい。
参照
GitHub – Pull Requestをレビュー【コメントの書き方と修正依頼】 | Howpon[ハウポン]
プルリクエストでの「Start a review」と「Add single comment」の使い分けがよくわかってなかったのでまとめてみた - Beeeat’s log
モダンなPull Requestの回し方 || log.pocka.io
モダンなPull Requestの回し方 || log.pocka.io