Git
GitLab
レビュー
ドキュメント
仕様書

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

はじめに

開発者のみなさんこんにちは。チームで開発するとき、外部仕様の設計資料や、プログラムの設計資料を作成して、チームメンバーにレビューしてもらうことがあると思います。

最近は設計資料や、説明資料を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の画面に行きましょう。

mr.PNG

MergeRequestという文字が見えますね!これをクリックします。するとMerge Request作成画面に遷移します。

mr2.PNG

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をクリックして完了です。チャットやメールでレビューを依頼しましょう。

mr3.PNG

参考:
How to create a merge request
https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html

レビューする場合

続いて、レビュー依頼をもらったひとの立場で説明します。まず作成されたmerge requestの本文を読み、趣旨を理解したら変更内容を見ていきましょう。

画面中断のCommitsをクリックするとコミットの情報が表示され、Changesをクリックすると差分が表示されます。Changesをクリックしてみましょう。

mr4.PNG

そうするとside-by-sideのdiffが表示されます。通常のソースコード修正では差分を見るときに重宝しますが、ドキュメントの場合も同様です。

また、右側の行番号あたりにマウスをあわせると吹き出しマークが出てきて、クリックするとコメントを記入することができます。ここで記載したコメントは自動的にDiscussionに表示されるので、通常はこの画面でコメントを記載することになるでしょう。

mr5.PNG

このようにしょうもないコメントを記載するとDiscussion欄に表示されました!これに対してreplyもできます。なおコード上に記載したコメントは解決されるべき問題としてカウントされます。Resolve discussionボタンを押すと解決されたとカウントされます。

右上の0/1 discussion resolvedを目安にmerge可否を判断するのもよいでしょう。

特定行に関連しない、例えば全体に関わる指摘はdiscussion欄に直接記載してよいです。(その場合はResolve discussionとしてはカウントされません)

今回は既存の仕様書の修正ではなく、新規作成の場合のストーリーでした。その場合は差分は重要ではありません。markdownで記載した場合、レンダリングされて表示してほしいですよね。

source branchのfilesにいってもいいのですが、面倒なので、Changesの各ファイル右上の View file~をクリックしましょう。最新コミットのファイルを見ることができます。

mr6.PNG

おわりに

メールでのレビューだと指摘内容が埋もれてしまいますし、修正差分がわかりません。生産物のレビューはMergeRequestの単位で行うと指摘と修正差分が一括で管理されるので便利です。

メールやチャットは"通知"としての役割に限定し、レビューはGitlabを通じて行いたいですね。