document
GitLab
仕様書
MergeRequest

GitlabのMergeRequestに対するコメントはcommitよりchangesに書くほうがよさげ

はじめに

Gitlabでドキュメントやコードレビューをしているみなさんこんにちは。

前回、通常コードレビューで使うMergeRequestをドキュメントでも使ってみようという記事を書きました。

仕様書のレビューをGitlabのMerge Requestでやろう!

今回はその続きで、レビューのコメントの付け方についてです。

前回同様、ドキュメントに閉じた話ではなく、通常のコードレビューでも共通している話になります。

準備

適当にMergeRequestを作ってみました。

mr1.png

MergeRequestでのコメントのつけかた

コメントの付け方には3通りあります。

1. commitで行にコメントする

MergeRequestのCommitsタブから対象のCommitを選択し、Commitの画面に移動します。マウスを行数のあたりに合わせると吹き出しが出るのでクリックしましょう。

コミットの13行目にコメントをしてみました。

mr2.PNG

2. commitにコメントする

こちらも同じくMergeRequestのCommitsタブから対象のCommitを選択し、Commitの画面に移動します。下部のコメント欄にコメントできます。

これは特定行に関係なく、commit全体にコメントする感じになりますね。

mr3.PNG

下に書き込まれました。

mr4.PNG

3. changesで行にコメントする

次はchangesにコメントです。

MergeRequestのChangesタブをクリックし、1. commitで行にコメントすると同様に行数の付近にマウスを合わせると吹き出しが出るのでコメントできます。

changesはMergeRequestを送っているbranchの1番新しいコミットと、Merge先との差分を示しています。

mr5.PNG

書き込むとcommitのときと違ってResolve discussionと出ていますね。

mr6.PNG

さらに追加でcommitする

指摘をされたので追加commitで修正しましょう。

コメントがあった13行目をたのしいからたのしくないに変更しました。

mr7.PNG

changesを見てみると、先ほど指摘したコメントは消えてしまいました。

mr8.PNG

discussionには残っています。

discussionとは

解決すべき議論ということで、changesにコメントした場合はそれはdiscussionとしてカウントされます。(このボタンを押すと未解決discussionにjumpします。便利。)

mr9.PNG

この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に反映されるものの、解決すべきものとしては扱われません。補足情報を付加するだとか、修正を要求しないものに対して行うのが良いでしょう。

おわりに

「指摘したけど反映されていない!」「指摘を管理するのがタイヘン。。。」そんな世界とはおさらばして、たのしいドキュメント開発ライフを!