はじめに
Gitlabでドキュメントやコードレビューをしているみなさんこんにちは。
前回、通常コードレビューで使うMergeRequestをドキュメントでも使ってみようという記事を書きました。
仕様書のレビューをGitlabのMerge Requestでやろう！
今回はその続きで、レビューのコメントの付け方についてです。
前回同様、ドキュメントに閉じた話ではなく、通常のコードレビューでも共通している話になります。
準備
適当にMergeRequestを作ってみました。
MergeRequestでのコメントのつけかた
コメントの付け方には3通りあります。
1. commitで行にコメントする
MergeRequestのCommitsタブから対象のCommitを選択し、Commitの画面に移動します。マウスを行数のあたりに合わせると吹き出しが出るのでクリックしましょう。
コミットの13行目にコメントをしてみました。
2. commitにコメントする
こちらも同じくMergeRequestのCommitsタブから対象のCommitを選択し、Commitの画面に移動します。下部のコメント欄にコメントできます。
これは特定行に関係なく、commit全体にコメントする感じになりますね。
下に書き込まれました。
3. changesで行にコメントする
次はchangesにコメントです。
MergeRequestのChangesタブをクリックし、1. commitで行にコメントすると同様に行数の付近にマウスを合わせると吹き出しが出るのでコメントできます。
changesはMergeRequestを送っているbranchの1番新しいコミットと、Merge先との差分を示しています。
書き込むとcommitのときと違ってResolve discussionと出ていますね。
さらに追加でcommitする
指摘をされたので追加commitで修正しましょう。
コメントがあった13行目をたのしいからたのしくないに変更しました。
changesを見てみると、先ほど指摘したコメントは消えてしまいました。
discussionには残っています。
discussionとは
解決すべき議論ということで、changesにコメントした場合はそれはdiscussionとしてカウントされます。(このボタンを押すと未解決discussionにjumpします。便利。)
このdiscussionはどういう意図でつけられているのか、公式ドキュメントを見てみましょう。
GitLab Documentation - User documentation - Discussions
Commit discussions in the context of a merge requestにある通り、changesに書き込んだ場合には解決すべき議論としてdiscussionに反映されます。
Discussions created this way will only appear in the original merge request and not when navigating to that commit under your project's Repository > Commits page.
しかし、commitに紐づいたコメントはそのようにならないため、個別にコミットページに行って確認しないといけません。
(余談)このドキュメント見てて気づいたんですが画像にコメントもできるんですね、すごい
まとめ
今回わかったこと
- MRに対するコメントの付け方は3つあり、discussionになるのはchangesにコメントした場合のみ
- changesに書き込んだコメントは、コメントをつけた行が変更されるとchangesからは表示されなくなる
使い分け
チーム内の運用ポリシーによりますが、指摘が解決されたかどうかをresolve discuttionで把握できたほうが便利なので、原則changesにコメントするほうが良いでしょう。反映を確認したら指摘者がresolveすればよいですね。
コミットに対するコメントはdiscussionに反映されるものの、解決すべきものとしては扱われません。補足情報を付加するだとか、修正を要求しないものに対して行うのが良いでしょう。
おわりに
「指摘したけど反映されていない！」「指摘を管理するのがタイヘン。。。」そんな世界とはおさらばして、たのしいドキュメント開発ライフを！