doc/tutorials/reviews/_index.md
Merge request reviews help ensure only high-quality code makes it into your codebase. This tutorial shows you how to review a merge request in GitLab. It guides you through the structure of the merge request itself, and then the process of giving constructive, helpful feedback. By the end of the tutorial, you're ready to approve the merge request, or request more changes.
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see merge request review.
<!-- Video published on 2023-04-29 -->To review a merge request:
Merge requests have a secondary menu with four options. You use these areas of a merge request at different times during your review:
The sidebar in the Overview tab contains important metadata about the merge request itself: the assignee, reviewer, labels, milestone, and time tracking.
Before you jump into reviewing the code, you should assess the merge request at a high level. Understand the context and purpose of the merge request: what it is trying to do, and why. Compare those needs to your skillset, while asking yourself these questions:
Start by looking at the description of the merge request. It should be the solution to a problem or a feature request in an issue.
Below the description, check the merge request widget to understand the current status of this work. This example shows a merge widget for a merge request that is missing approvals, is still in draft mode, and has open discussion threads:
If related issues exist, and the merge request feels complex enough that you need more information, scan through the issue descriptions.
What labels does it have? Labels can provide cues to the content of the merge request. Depending on your team's workflow, incomplete or missing labels might be innocuous, or might indicate this merge request lacks full information.
In this example, even if the exact labels are unfamiliar to you, you can determine this merge request is about a database bug:
Who are the reviewers? Scan the names in the reviewer list. Do they match the type of work you'd expect, based on the description and (optionally) the labels? Consider both who is present, and who is absent. What do those names tell you about where this merge request is in its review cycle? Do you need to add or remove anyone?
Have any reviewers already approved? If you know those reviewers and their areas of expertise, you can gain some idea of what aspects of the proposed changes need your attention.
In this example, both Thomas and Nick are reviewers. Thomas has not yet reviewed ({{< icon name="dotted-circle" >}}) the merge request. Nick has reviewed and approved ({{< icon name="check-circle" >}}):
On the Overview page, read the comments left by the author and others. Keep those discussions in mind as you read the code changes.
Do you see evidence of previous reviews in the comments? A large number of comments might influence how deeply you want to review this work.
Now you're ready to read the proposed changes. For large merge requests, skim the changes before diving in. Build your understanding of what to expect before you begin to read changes line by line.
[!note] The diffs displayed in the Changes tab are dense with information. To learn how to get the most out of this page, see Changes in merge requests.
When you first open the Changes page, focus on the broader details first:
What files have changed? Expand the file browser ({{< icon name="file-tree" >}}) to see the list of changed files. Are you familiar with these files? What part of the codebase are these files in?
Does the file list match your expectations? You've already read the description of the merge request. Are these the files you'd expect to see changed for this kind of work? Pay extra attention to changes to unexpected files, or if changes you'd expect to see are missing.
Are lines added, removed, or changed? These numbers tell you what kind of work to expect in your deeper read: a new feature, a removed feature, or changes in behavior?
Were any tests changed? Are any of the files part of your testing suite? If not, you might need to nudge the author to update tests.
Are feature flags used? If you see feature flags, make a note to check their use in your deeper read-through.
When you've finished skimming the changes, you're ready to read the changes line by line!
You now have a broad idea of the changes this merge request contains. It's time to dive in and read the changes in full. Stay aware of where your knowledge is strong, and where it is weak. Do you know this project well? Are the changes written in a language you're comfortable working in?
Different types of changes have different effects on your codebase. Consider, in broad terms:
Unfortunately, we can't give you much guidance here. Every project is different! Without knowing your application firsthand, we can't tell you how to test the changes, but we can offer some questions to consider:
Does it work? It's a deceptively simple question, but it's important to keep in mind. Code can be ugly, convoluted, and undocumented, but still work.
How far along is the review process? Is it early or late in the review process? Are you a specialist?
While you're testing the code, you should also check the pipeline status. While you still haven't written any review comments yet, you're nearly ready.
Go to the Pipelines tab of the merge request, and verify the pipeline status. Approve the merge request only if the pipeline has succeeded. In this example, multiple jobs have failed:
Sometimes merge request reviews are not straightforward and require a back-and-forth between the assignee and reviewers. If you're re-reviewing work, go to the Commits page for this merge request, and read the contents of the commits added after your last review.
Do these commits address your concerns from your initial review?
You've now done the prep work for a thoughtful, helpful review. When you first skimmed through the merge request, you didn't have full knowledge of the line-level changes. Now you do! Before you start writing, step back from the line-by-line view of the merge request and think about it broadly again. You now know what the merge request is trying to do, and how it's doing it.
The best and most helpful code reviews don't just focus on line-by-line fixes. They also consider long-term concerns, like maintainability and technical debt.
It's time to give feedback!
When you're new to reviewing merge requests, you might be surprised at how much time you spend thinking before you write your first comment. As you become more familiar with a codebase, you'll understand new merge requests faster. However - you'll probably also start taking on more complex reviews.
The Start a review feature enables you to write your thoughts down in pending comments. These comments aren't visible to anyone else until you submit your review. This avoids message overload to your recipients, and gives you a chance to recheck (and change) your words before you publish.
Remember to be constructive and kind. The structure of conventional comments can help you write comments that are both thoughtful and constructive.
First, write your comments you want to attach to specific lines or files:
Select the Changes tab.
When you find lines you want to ask questions about, or provide feedback on, select Add a comment to this line ({{< icon name="comment" >}}) in the gutter. This expands the diff lines and displays a comment box.
You can also select multiple lines, or select an entire file to comment on:
In the text area, write your first comment. To keep your comments private until the end of your review, select Start a review below your comment.
Provide suggestions when the fixes are easy for you to draft, or if you want to show the author a better approach. If the code changes are too big or complex for the suggestion format, leave a comment requesting changes.
Continue commenting on files and individual lines of code. After each comment, select Add to review.
As you work, you can use quick actions, like
/label or /assign_reviewer, in your review comments. Your pending comments
show your requested actions, but the actions aren't performed until you submit your review.
(Later, you can submit your review with the /submit_review quick action, too!)
You've added your file- and line-specific feedback, and now you're ready to summarize your review. It's time to think broadly, one last time.
Go back to the Overview page of the merge request.
Scan your pending comments. They should be helpful, thoughtful, kind, and - most importantly - actionable. Have you given the author an obvious next step to fix any problems you found?
Consider your tone. Are you teaching, debating, or discussing? Do your comments achieve your goal? If you were the author, would you know what to do next? Reinforce good behaviors, and nudge the author away from bad behaviors.
Do your comments still make sense? In large merge requests, you might find that some comments are no longer useful, or some questions that you had have been answered in the meantime.
Start threads for generalized feedback. Make sure unrelated items aren't clumped together in the same comment, so that when threads resolve, unaddressed feedback isn't hidden. Some possible topics:
Start a new thread for your summary comment. Make sure you mention the author's username, in case they work from to-do items. State clearly:
On the top right, select Your review to show details about your review:
Review your pending comments. Edit them as needed.
Select the outcome of your review.
Optional. Write a summary of your review. GitLab Premium and Ultimate users can select Add summary ({{< icon name="tanuki-ai" >}}) to create a summary for you. Include any quick actions you want performed.
You can also use the /submit_review quick action in the text of a non-review comment.
If you approve a merge request and are shown in the reviewer list, a green check mark {{< icon name="check-circle-filled" >}} displays next to your name.
After you provide your feedback, tidy up.