Welcome to our guide for using our issue tracker, repository platform and task manager, GitLab. All information here is explained (by a team of technical writers, which is probably better than this guide :) ) at GitLab user documentation, so don't hesitate to consult that and search there for better and deeper information. This guide will focus on the basics for GNOME people new to GitLab (and GitHub alike) workflow.

Log In

If you are a member at GNOME or you have commit access, most probably you have a LDAP account at GNOME. If you do, please use your account to log in. In case you lost your password visit the recovery page for your account.

If you are an external user or reporter, you can use GitHub, GitLab or Gmail accounts to log in, or optionally create a new one inside GNOME GitLab.

Code Projects

All GNOME code projects are hosted in the GNOME group.

Permissions

All people part of the gnomecvs group have developer permissions. These permissions are set automatically and shouldn't be modified. As a developer you can give other up to "reporter" permission, which is useful for non-code contributors like the bug squad team or designers.

Non GNOME member set up

First of all, welcome to GNOME!

In order to contribute follow the next steps:

  • make sure you are logged in.

  • upload your ssh keys to GitLab if you didn't do so yet. You can do it at the ssh keys options in GitLab. You will find there instructions to generate one if necessary.

GitLab workflow for code contribution

Using the canonical project - GNOME developer

If you are a developer or maintainer of a project, most likely you don't need to create a fork to work on your project. You can use branches directly in the canonical project. The workflow to fix an issue is as follows:

  1. Go to the issue and press create a merge request or create a branch in the command line.
  2. Locally check out the branch
  3. Locally create commit with comment "Closes: #ISSUE_NUMBER"
  4. Push branch
  5. In the command line a link to create or visit the merge request will be generated, click it. Optionally, you can create a merge request from a branch in GitLab UI.

(Note, you can also use the "Non GNOME developer" workflow below if you prefer.)

Using a fork - Non GNOME developer

  1. In the GitLab UI, go to the project you want to contribute to and click "Fork" and fork it under your username.

  2. Clone your forked repository with git clone forked_project

  3. Add the original repository as upstream with: git remote add upstream https://gitlab.gnome.org/GNOME/projectname

  4. Create a branch for your work using git checkout -b my_work

  5. Locally create commit with comment "Closes: #ISSUE_NUMBER"
  6. Push your branch to your fork with git push origin HEAD

  7. Create merge request either by the link that shows in the command line after pushing or in the GitLab UI clicking "Create merge request" in your branch.

Optionally, instead of creating a branch you can push your current branch to a different remote branch like git push origin HEAD:remote_branch_name.

Review and applying changes

Here let's explain the steps to be followed by each side, contributor and reviewer, of a regular workflow.

Once the contributor creates a merge request, the maintainer can test the changes locally. You will see instructions to do so in the same merge request.

Once the changes are tested locally, the maintainer can review the code. To do so, go to the "changes" or "commits" tab and review the changes in there. It will create "discussions" entities, which need to be resolved and allow sub discussions in them to keep things organized.

Now the contributor can make changes and upload the new version. To do so, make your changes locally, rebase your branch, and do a push with the force option, like git push origin HEAD --force, this will replace the branch in the merge request with the new content.

Merging

Usually you will wait for the CI to finish, and if things look fine now, you can merge the merge request clicking "merge". Note there is an option to remove the branch associated with the merge request, usually you would want to do it.

If you want to merge in the command line feel free to do it and push directly from there, just make sure the branch in the merge request is the same as you have locally, otherwise the automation in GitLab won't fire up and you will have to close the merge request yourself.

Problematic cases

  • The merge request has conflicts

Ask the contributor to fix them and upload a new version, or as maintainer do it yourself in the GitLab UI with the built-in conflict merge resolution.

  • The merge request needs modifications

Modify locally and create a new merge request with the new code, referencing the previous merge request.

Here you can see these problems don't have an ideal solution. The first one doesn't allow you to do it locally, because then you don't have a way to override the branch from someone else. The second one suffers the same problem.

The solution is creating a new merge request or just pushing directly and closing manually the merge request. We are tracking this issue upstream here and it's part of our list for improvements.

GitLab workflow for Bug Squad

The Bug Squad usually triages and manages issues, with GitLab you will use labels for most of the tasks. If you want to become part of the Bug Squad, ask a member of the current Bug Squad or the maintainer of the project you are managing issues for.

Permissions

First, you should have reporter permissions in a single project or in the GNOME group. This will allow you to manage issues for most part of it.

Issues

Issues are the main entity for bugs, features and tasks. Usually you will see the issues of a specific project like nautilus, or the GNOME group as a whole.

You can create, close, mark as duplicate, move to a different project, etc.

The most special case is to mark an issue as duplicate, which right now is done with what is called "quick actions". To mark an issue as duplicated, in the comment section put /duplicate #number and it will close as duplicate of that issue. Since this is not ideal, we are tracking how to improve this upstream.

You can read more about issues in the upstream documentation.

Labels

Labels are the core part of the workflow for the Bug Squad. You can read in the upstream documentation what are them, but basically are tags you can put to a issue.

We created a few that are shared for the GNOME group, you can take a look at them here, as you can see they use different colors to differentiate between types and have a prefixed number for correct ordering. Each project can have its own labels, for instance this is useful for components and they use the number "5" for it, and you can see as an example nautilus. You can take a look at the discussion we had about labels in case you have some feedback.

Non-code projects

GitLab can be used also for non-code projects, more like a task manager, thanks to the labels, kanban board, and other features. This guide can be useful for example for the engagement team or the design team.

GitLab can be quite noisy for a non-technical person using it, although effort is being made to improve that, there is still some learning that needs to be done. Once is done, it should be quite straigforward and if you need any help with setting up automation and try to get all the power from the product, feel free to contact Carlossoriano. The basic usage is explained in the following sections.

Looking at issues (a.k.a tasks and community requests)

GitLab has the concept of "issues" to define tasks, requests or problems which you have a variety of tools to manage and track. From now on we will call them "issues". If you want to see all issues click in the issues button in the left sidebar. For example here are the issues of the engagement team.

issues.png

You can also see all the kind of issues using what is called "labels" that is used to mark and be able to filter different types of issues/tasks/requests. You can see them clicking in the sidebar labels. You can see an example of the "social media" requests by the engagement team here.

Adding images

You can use the buttons you have on the bottom when commenting on an issue or simply drag and drop your images from your desktop.

add_images.png

Due dates for tasks

You can look in the sidebar, the section "due date" for when a issue should be done. You can also edit it clicking on it to change it.

due_date.png

Subscribing to changes in a issue

Inside the issue, click the button "subscribe". You can click it again to unsubscribe.

subscribe_issue.png

Requesting attention/notifying someone

You can request the attention of people by doing "@" and their name. For example @sri. The one that was mentioned will receive an email and a ToDo item.

mentioning.png

Assigning to an issue

You can either just comment in the issue, or click in the right sidebar to "assignee" and add yourself.

assignee.png

GitLab (last edited 2017-12-05 21:26:01 by PhilipChimento)