MediaWiki

GitLab/Workflows/Making a merge request

< GitLab | Workflows
UML diagram showing the trusted contributor GitLab workflow

Clone a repository from GitLab

edit

If you are the owner or have developer-level access to a repository, you can clone it directly and then continue with Create a branch and the following sections.

If you don't have developer-level access to the repository, first create a fork and clone that fork instead. See Fork and clone a repository from GitLab for details.

To clone a repository: 

git clone <repository address>
Example:
user@machine:~/src/ $ git clone git@gitlab.wikimedia.org:repos/releng/blubber.git 
Cloning into 'blubber'...
remote: Enumerating objects: 823860, done.
remote: Counting objects: 100% (823860/823860), done.
remote: Compressing objects: 100% (121686/121686), done.
remote: Total 823860 (delta 699470), reused 823820 (delta 699435), pack-reused 0
Receiving objects: 100% (823860/823860), 250.40 MiB

Fork and clone a repository from GitLab

edit
 
UML diagram showing new volunteer GitLab workflow

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 https://gitlab.wikimedia.org/repos/releng/blubber, and click "Fork" in the upper righthand corner.

Next, select your username in the namespace dropdown under "Project URL". You may see a number of options, depending on what other namespaces you have access to. When done, click the "Fork project" button.

If you've already cloned the original repository and don't want to clone the fork as well, you can add it as a remote to the cloned repository instead. This is an advanced scenario described in Working with multiple remotes.

Clone the forked repository. Be sure to replace <your username> with your GitLab username: 

git clone git@gitlab.wikimedia.org:<your username>/blubber.git
Example:
user@machine:~/src/ $ git clone git@gitlab.wikimedia.org:user/blubber.git 
Cloning into 'blubber'...
remote: Enumerating objects: 823860, done.
remote: Counting objects: 100% (823860/823860), done.
remote: Compressing objects: 100% (121686/121686), done.
remote: Total 823860 (delta 699470), reused 823820 (delta 699435), pack-reused 0
Receiving objects: 100% (823860/823860), 250.40 MiB

Next, continue as described in Create a branch and the following sections.

Create a branch

edit

To create a new branch: 

git checkout -b <branch name>

Use the following branch naming convention: work/<your username>/<topic>.

Example:
user@machine:~/src/blubber $ git checkout -b work/user/refactor-readme
Switched to a new branch 'work/user/refactor-readme'

Make your changes

edit

Write some code and save your changes.

Stage and commit your changes

edit

Let's say you've edited the README.md in blubber. You should be able to see this using git status:

Example:
user@machine:~/src/blubber $ git status
On branch work/user/refactor-readme
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   README.md

Stage the file and commit, following the commit message guidelines: 

git add <file name>
git commit -m '<commit message>'
Example:
user@machine:~/src/blubber $ git add README.md

user@machine:~/src/blubber $ git commit -m 'Updated README.md'
[work/user/refactor-readme 21c7972d3f8] Updated README.md
 1 file changed, 2 insertions(+)

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

Example:
commit 21c7972d3f819005dc00fa0f3f5cd196c3bb46b4 (HEAD -> work/user/refactor-readme)
Author: Some User <user@example.com>
Date:   Wed Sep 23 15:45:30 2020 -0600

    Updated README.md

Push your commit to GitLab

edit

Push to a branch on the origin: 

git push origin <branch name>
Example:
user@machine:~/src/blubber $ git push origin work/user/refactor-readme
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 352 bytes | 176.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: 
remote: ========================================================================
remote: 
remote:                       🚧 This instance is [under
remote:      construction](https://www.mediawiki.org/wiki/GitLab/Roadmap);
remote:   expect occasional downtime. Runners available in /repos. Questions?
remote:                       Ask in [#wikimedia-gitlab on
remote:    libera.chat](https://web.libera.chat/?channel=#wikimedia-gitlab),
remote:                                 or under
remote:    [GitLab](https://phabricator.wikimedia.org/project/board/5057/) on
remote:                               Phabricator.
remote: 
remote: ========================================================================
remote: 
remote: To create a merge request for work/user/refactor-readme, visit:
remote:   https://gitlab.wikimedia.org/repos/releng/blubber/-/merge_requests/new?merge_request%5Bsource_branch%5D=work%2Fuser%2Frefactor-readme
remote: 
To gitlab.mediawiki.org:repos/releng/blubber.git
 * [new branch]              work/user/refactor-readme -> work/user/refactor-readme

Create a merge request on GitLab

edit

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 GitLab instance, navigate to the branch list for the repository, and click the "Merge request" button in the listing.

 
A screenshot of a GitLab Community Edition listing of branches on a repository.
If your branch is in a fork under your user account, remember to look there instead of in the origin repository.

Provide an informative title and description for the merge request, and @-mention the users you'd like to see review your code. You should be able to use the full range of syntax in GitLab Markdown.

Merge options

edit

In the "Merge options" section:

  • Check "Delete source branch when merge request is accepted" to avoid cluttering the repository with already-merged feature branches. (This is probably the default.)
  • In the general case, you should use "Squash commits when merge request is accepted". (This is probably the default.)
    • Omit this 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.

Draft / WIP merge requests

edit

If you want to let reviewers know that your change is a work in progress and prevent accidental merges, you can use a draft merge request. Prefix your merge request title with Draft: . This will display a notice and disable "merge" button for reviewers.

Adding commits to a merge request

edit

Making new commits

edit

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

git push origin <branch name>

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

edit

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. With this approach it is still very easy for reviewers to see what changed since the last push to the merge request. 

git push -f origin <branch name>
Example:
user@machine:~/src/blubber $ git status        
On branch work/user/refactor-readme
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

# Add your changed file:
user@machine:~/src/blubber $ git add README.md

# Amend the previous commit:
user@machine:~/src/blubber $ git commit --amend
[work/user/refactor-readme b867605eb86] README.md: Add some whitespace and rework lists
 Date: Fri Sep 25 14:29:44 2020 -0600
 1 file changed, 8 insertions(+), 6 deletions(-)

# Push to your remote:
user@machine:~/src/blubber $ git push -f origin work/user/refactor-readme
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 403 bytes | 403.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0)
remote: 
remote: ========================================================================
remote: 
remote:                       🚧 This instance is [under
remote:      construction](https://www.mediawiki.org/wiki/GitLab/Roadmap);
remote:   expect occasional downtime. Runners available in /repos. Questions?
remote:                       Ask in [#wikimedia-gitlab on
remote:    libera.chat](https://web.libera.chat/?channel=#wikimedia-gitlab),
remote:                                 or under
remote:    [GitLab](https://phabricator.wikimedia.org/project/board/5057/) on
remote:                               Phabricator.
remote: 
remote: ========================================================================
remote: 
remote: To create a merge request for work/user/refactor-readme, visit:
remote:   https://gitlab.wikimedia.org/user/blubber/-/merge_requests/new?merge_request%5Bsource_branch%5D=work%2Fuser%2Frefactor-readme
remote: 
To https://gitlab.wikimedia.org:brennen/blubber.git
 + 4b860bb6680...b867605eb86 work/user/refactor-readme -> work/user/refactor-readme (forced update)

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.

Getting code review

edit

Once you've submitted a merge request, someone will need to review it. In addition to @-mentioning appropriate users in your merge request description or comments, you can assign a single reviewer. Do this by clicking "Edit" next to "Reviewers" in the sidebar at the right side of the page when viewing a merge request.

You may also use "Assignee" to indicate ownership of the merge request, responsibility for merging, etc., as useful to your workflow.

Please see Code review for documentation on reviewing code.

Local repository migration

edit

Update your remote

edit

When we migrate from Gerrit to GitLab you will need to update your remote repository url locally:

Remote url update:
$ git remote set-url origin git@gitlab.wikimedia.org:[repo-name].git
# or 
$ git remote set-url origin https://gitlab.wikimedia.org/[repo-name].git

Rename "master" to "main"

edit

As part of the migration to GitLab, we are changing the mainline branch from master to main.

To update your local checkout (after changing your remote):

Branch renaming:
# Rename the branch locally
$ git branch -m master main

# Reset your upstream branch
$ git fetch
$ git branch --unset-upstream
$ git branch --set-upstream-to=origin/main

# Change the remote head
$ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

This transition is documented on Phabricator on phab:T281593 (and phab:T254646).

Working with multiple remotes

edit

If you've cloned a repository but also had to create a fork due to insufficient permissions, you don't have to clone the fork repo as well. Instead, you can use your original repository with multiple remotes. To do that, add your fork as a remote:

Example:
user@machine:~/src/blubber $ git remote add fork git@gitlab.wikimedia.org:<your username>/blubber.git

If you've done this successfully, it should show up on the list of your remotes:

Example:
# Check remotes:
user@machine:~/src/blubber $ git remote -v
fork    git@gitlab.wikimedia.org:<your username>/blubber.git (fetch)
fork    git@gitlab.wikimedia.org:<your username>/blubber.git (push)
origin  git@gitlab.wikimedia.org:repos/releng/blubber.git (fetch)
origin  git@gitlab.wikimedia.org:repos/releng/blubber.git (push)

You can now push to your fork remote as described in Push your commit to GitLab by using git push fork instead of git push origin.

Sources and further reading

edit

There's a lot of quality documentation available for GitLab, although navigating it can be a bit tricky.

Retrieved from "https://www.mediawiki.org/w/index.php?title=GitLab/Workflows/Making_a_merge_request&oldid=6850287"