はじめに
開発者のみなさんこんにちは。チームで開発するとき、外部仕様の設計資料や、プログラムの設計資料を作成して、チームメンバーにレビューしてもらうことがあると思います。
最近は設計資料や、説明資料をGitlabで管理しているチームも多いと思います。せっかくGitlabを使っているので、ぜひMerge Request機能を使ってレビューをしてみましょう。
なおこの話はもともとソースコードレビューを行う方法であり、その活用範囲を仕様書等のドキュメントにも拡大しよう、という趣旨です。
Merge Requestとは
GithubのPull Requestに対応する機能のことです。
用語が異なる理由ですが、Contributionする際、Githubの場合はリポジトリをforkして行うことが主なので「自分の修正をpullしてよー！」ということからPull Requestと呼ぶのでしょう。Gitlabの場合は同一プロジェクト内のbranchのmergeを行うことが主なので、「自分のbranchをmergeしてよー！」ということからMerge Requestと呼ぶようです。
もちろん、GitlabもForkによるMerge Requestはできますし、GithubもbranchレベルでのPull Requestができます。慣習からくる差でしょう。
参考：
Pull Request / Merge Request の違い
https://qiita.com/pink/items/8ab3ecc270a9a7db46b4
レビューしてもらう場合
さて、レビューをしてもらうひとは、まずbranchをcheckoutしましょう。運用方法によりますが、master branchから自分専用のbranchをcheckoutします。
# git checkout -b design-review
これでdesign-reviewというブランチが(存在しなければ)作成されました。
次にこのブランチ内でレビュー対象ファイルを作成し、チェックインしましょう。
# git add hogehoge.md
# git commit -m "design review"
# git push -u origin design-review
これで作成したbranchがpushされました。続いてgitlabのGUIでbranchの画面に行きましょう。
MergeRequestという文字が見えますね！これをクリックします。するとMerge Request作成画面に遷移します。
titleにWIP: という文字をつけると、それはWork-In-Progressであることを示します。作業中でまだMergeできないんだけど見てほしいときや、実装前の仕様確認で先にMergeRequestを作成するときに用いられます。
本文に決まりはありませんが、私はファイルの説明と、観点、補足で自分が気になっていることを記載するといいと思います。
以下の1ファイルのレビューをお願いします。
# ファイルの説明
## sample.md
設計ファイルのサンプルです。qiitaに投稿するためのsampleです。
# 観点
* 適切なsampleになっているか
* sampleであることが伝わるか
# その他
* 何か気になることがあれば
レビュー対象が1人であればAssigneeを設定してよいですが、2人以上に見てもらうことが多いので普段は設定しません。Milestoneやlabelは各チームの運用ルールに従ってください。
Source branchは、merge request作成時のbranchが選択されます。target branchのデフォルトはmasterのようです。必要に応じて変更してください。
Submit Merge Requestをクリックして完了です。チャットやメールでレビューを依頼しましょう。
参考：
How to create a merge request
https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html
レビューする場合
続いて、レビュー依頼をもらったひとの立場で説明します。まず作成されたmerge requestの本文を読み、趣旨を理解したら変更内容を見ていきましょう。
画面中断のCommitsをクリックするとコミットの情報が表示され、Changesをクリックすると差分が表示されます。Changesをクリックしてみましょう。
そうするとside-by-sideのdiffが表示されます。通常のソースコード修正では差分を見るときに重宝しますが、ドキュメントの場合も同様です。
また、右側の行番号あたりにマウスをあわせると吹き出しマークが出てきて、クリックするとコメントを記入することができます。ここで記載したコメントは自動的にDiscussionに表示されるので、通常はこの画面でコメントを記載することになるでしょう。
このようにしょうもないコメントを記載するとDiscussion欄に表示されました！これに対してreplyもできます。なおコード上に記載したコメントは解決されるべき問題としてカウントされます。Resolve discussionボタンを押すと解決されたとカウントされます。
右上の0/1 discussion resolvedを目安にmerge可否を判断するのもよいでしょう。
特定行に関連しない、例えば全体に関わる指摘はdiscussion欄に直接記載してよいです。（その場合はResolve discussionとしてはカウントされません)
今回は既存の仕様書の修正ではなく、新規作成の場合のストーリーでした。その場合は差分は重要ではありません。markdownで記載した場合、レンダリングされて表示してほしいですよね。
source branchのfilesにいってもいいのですが、面倒なので、Changesの各ファイル右上の View file～をクリックしましょう。最新コミットのファイルを見ることができます。
おわりに
メールでのレビューだと指摘内容が埋もれてしまいますし、修正差分がわかりません。生産物のレビューはMergeRequestの単位で行うと指摘と修正差分が一括で管理されるので便利です。
メールやチャットは"通知"としての役割に限定し、レビューはGitlabを通じて行いたいですね。