GitLab/Workflows/Code review

= Reviewing code on GitLab =

This document is a work in progress.

For the basics of signing up for a GitLab account and submitting changes as a merge request, please see GitLab_consultation/Workflows.

Review before merge
It's important to us to have a review-before-merge workflow for MediaWiki core and also for any extension we deploy.

Review scores
(TODO: Not sure about how to frame this topic. Maybe this fits better in a dedicated “GitLab for Gerrit users” document, and the discussion here should only focus on the GitLab side.)

Gerrit supports code reviews ranging from -2 to +2 on changes. On GitLab, these roughly correspond to:


 * -2: No direct equivalent. If you want to make sure that no one fails to notice your objection before merging the change, you can edit the merge request title or description, e. g. adding the note DNM.
 * -1: Leave a comment or start a thread with your objection.
 * 0: Leave a comment or start a thread. (On Gerrit, you can also change your vote back to 0 to remove a different vote, such as a +1; in GitLab, this would mean revoking your approval.)
 * +1: Approve the merge request.
 * +2: Merge the merge request. (TODO: will we still have a gate-and-submit build and automatic merges?)

Comments and threads
Gitlab, like Gerrit, supports threaded discussion. Replies can be linked with a comment, and a whole thread can be marked as resolved. On Gerrit, resolving/unresolving a thread is only possible when commenting on it, and so it is conventional to resolve a thread with a comment “Done” if there is nothing else to say. On GitLab, on the other hand, this is not necessary: A thread can be marked as resolved or unresolved without requiring a new comment.

Inline suggestions
GitLab comments support inline suggestions for simple changes. This is a powerful feature, particularly for small, uncontroversial changes such as typo-fixes or style tweaks.

As a reviewer, you can add a suggestion using the following syntax (also available by clicking the "Insert suggestion" button on the comment formatting toolbar):

```suggestion:-0+0 replacement text here ```

Best practices:


 * Use inline suggestions for minor changes (typos, style issues, clarifying comments).
 * Multiple suggestions should generally be applied as a batch.
 * A merge request with accepted suggestions should typically be squashed on merge in order to avoid noisy commits.