GitLab/Workflows

= Introduction =

GitLab is a code hosting, review, and continuous integration platform. We're running a community consultation on moving from Gerrit to GitLab for Wikimedia code review.

This aims to be a tutorial describing workflows for using our trial GitLab instance for Wikimedia development. Depending on the result of the consultation, it may evolve into a reference for production use.

Assumptions
This document is written with a number of underlying assumptions, based on feedback from the GitLab consultation and recent experimentation.


 * Many regular contributors to a repository in GitLab will have "Developer"-level permissions to create branches directly on the mainline copy of a project's repository, and merge changes from merge requests.  While not identical, this is roughly equivalent to +2 rights on Gerrit.
 * As on Gerrit, default branches will be protected, and review will be required before a merge.
 * Location of branches
 * Users with permission to create branches will create work branches directly on the mainline repositories and submit merge requests for these.
 * Users without permission to create branches will instead fork the repository to their own account and create a work branch there, then submit a merge request for those changes to the mainline repository.
 * Development flow
 * In most situations, branches will accumulate commits sequentially as they receive review, and be squashed to a single commit on merge into the default branch.
 * It's possible to rewrite history and force push to the branch associated with a merge request, so workflows involving rebasing or amending of commits will be supported to some degree.
 * Within a project, GitLab labels can serve roughly similar functions to Gerrit's notion of topics. This may not hold true across projects.

= Registering an account on gitlab-test =

Accounts on the test instance are not currently tied to Wikimedia developer accounts. Visit gitlab-test.wmcloud.org/users/sign_in to register.

Add an SSH key
Visit the SSH settings in your profile and add a public key. See the GitLab documentation for more details on this process.

= Making a GitLab Merge Request =

Create a branch
Use the convention :

Make your changes
Write some code and save your changes.

Stage and commit your changes
Let's say you've edited the  in. You should be able to see this using :

Stage the file and commit:

You should now be able to see this commit in the log:

Fork the repository
If you don't have developer-level permissions on the project you'd like to contribute to, you'll first need to copy the repository to your own account. This is known as "forking". Visit the repository page, for example gitlab-test.wmcloud.org/mediawiki/core, and click "Fork" in the upper righthand corner.

Next, add a remote for your fork:

If you've done this successfully, it should show up in your remotes:

Push your commit to GitLab
If you have commit access, you can push directly to a branch on the origin with.

If you're using a fork, push instead to the remote you added above with.

Create a Merge Request on GitLab
You may notice that GitLab responded to the push with a link to create a new merge request from your branch. You can follow that link directly, or visit the trial GitLab instance, navigate to the branch list for the repository, and click the "Merge request" button in the listing.



Provide an informative title and description for the merge request, and @-mention the users you'd like to see review your code.

Merge options
In the "Merge options" section:


 * Check "Delete source branch when merge request is accepted" to avoid cluttering the repository with already-merged feature branches.
 * In the general case, you should use "Squash commits when merge request is accepted".
 * This can be omitted if you plan to submit a merge request containing multiple commits.
 * If the logical structure of your change dictates multiple commits, you may use interactive rebase to achieve the desired history and force push to your work branch before merge. This is an advanced workflow, but supported.
 * Check "Allow commits from members who can merge to the target branch", unless you have a specific reason to prevent others from making changes.

Making new commits
Typically, you'll just make a new commit on your work branch, as usual, and push to the correct remote:

Or:

The new commit makes it very easy for reviewers to see what changed since they last saw the merge request, and will be squashed into the other commits when the pull request is merged, assuming that the pull request is set up to squash commits on merge (as recommended above).

Force pushing to a branch
If, instead, you wish to rewrite the history of the branch, for example by altering an existing commit or rebasing your work on top of upstream changes, GitLab allows force-pushing to a branch that's associated with a merge request.

This is mainly suitable for merge requests which are not meant to be squashed on merge, typically because they contain two or more commits that should remain separate. In that case, you clean up the history locally and then force-push it to update the merge request.

TODO: I wonder if it would make sense to still push  commits without force-pushing, and only do a  +   from time to time? I like the idea of this, but the autosquash feature is probably too complicated or confusing to users not familiar with it if there isn’t good support for it from the GitLab UI. --Lucas Werkmeister (WMDE) (talk) 17:19, 16 October 2020 (UTC)

= How code is reviewed in GitLab =

This section a work in progress.

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.

Who can review and merge code in GitLab
Any user should be able to comment on a merge request, however only users with Developer- or Maintainer-level permissions for a given repository can merge code.

Self-merge is discouraged by policy. Merging your own code without approval from a reviewer may be grounds for revocation of privileges.

Merging a change to the MediaWiki core or an extension deployed by Wikimedia is a big deal. Your merge could cause Wikipedia or other sites to fail. It could create a security vulnerability that allows attackers to delete or corrupt data, or to gain access to private information. And in the more common case, it could cause technical debt to increase if the code doesn't have tests, is poorly implemented or poorly socialized. You should carefully read this document and all relevant policies before merging a merge request.

Maintainer permissions are a strong expression of trust, and trust is maintained through good judgement and careful action.

In code review, design discussions, and bug comments, those with merge abilities have a special responsibility to see from others' points of view.

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. Unlike in Gerrit, this is available not just on file-level comments, but also on top-level comments that apply to the whole merge request / change.

''I think this will be important to explain, since it’s similar but still different from Gerrit and – as far as I’m aware – also GitHub. At least, it confused me a fair bit in my first test merge request, though I think I’m starting to figure it out. I made some experiments at https://gitlab-test.wmcloud.org/mediawiki/core/-/merge_requests/12 and will try to write something coherent for here later, maybe with screenshots, too.'' --Lucas Werkmeister (WMDE) (talk) 17:56, 16 October 2020 (UTC)

GitLab threads can be marked as resolved or unresolved. On Gerrit, the status of the thread can only be changed when you are adding a comment to it; the conventional way to resolve a thread when you have nothing else to say is to comment “Done”, and the Gerrit UI even has a dedicated button for this.

On GitLab, on the other hand, this is not necessary: A thread can be marked as resolved or unresolved without requiring a new comment. You might say that on GitLab, we’re done with “Done” comments. 🥁

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.