GitLab contribution workflow

Overview

Now, we want to collaborate with others in a structured way using a typical GitLab contribution workflow.

Tips for instructors

• Overall, we want to introduce the participants to a basic GitLab contribution workflow based on issues and merge requests. First, we explain the more generic, technical view of this workflow. Then the participants will gain first practical experiences by starting to work with the issue feature. Afterwards, a more concrete approach will be presented in context of the planets example and demonstrated by the instructors. Finally, the participants should be able to try out the entire workflow in the team exercise and apply the skills they have learnt throughout the workshop.
• Please consider that it is the first real interaction with GitLab for many participants. For that reason, please do not be too fast and explain clearly when participants should join in.
• Two instructors are recommended for the live demonstration of the contribution workflow and the team exercise.

Checkpoints:

• Please make sure that all participants use their own GitLab project to perform the live coding steps.
• Please make sure that all participants have found a team partner when performing the team exercise.

A typical GitLab contribution workflow

The contribution workflow clarifies how changes to the repository are planned, agreed upon, made and checked. The following workflow is especially suited for GitLab and you can use it as a basis for many types of projects.

1. Open an issue:
   • Detail the intended changes.
   • Notify potential stakeholders.
   • Discuss the details:
     • Clarify open questions.
     • When working face-to-face this can be kept to a minimum. Write down the decisions that were made in meetings or attach a protocol.
2. Open a merge request:
   • This signals that someone is working on the issue.
   • A merge request automatically creates a feature branch on which you can perform your work.
   • Make changes iteratively:
     • Add commits to the branch.
     • When satisfied request a review of the changes made.
     • Adapt according to the reviews.
3. Decide whether:
   • The changes can be merged into the main branch (merge the changes).
   • The changes are not suited for the integration into the main branch (close the merge request).

Why should you think about your contribution workflow?

• Agreeing on how to handle day-to-day operations increases productivity and reduces the potential for miscommunication.
  • Reduces onboarding time for new project members.
  • Reduces setup time for new projects.
• Workflows that deal with similar types of projects should be similar.
  • There is no “one workflow to rule them all”!
  • Adapt workflows to team or project specific needs.

Exploring the GitLab contribution workflow

Issues are the starting point of our contribution workflow. They are a conversation-style medium for outlining, planning and managing tasks and processes. You can find a real world example from GitLab itself here: GitLab Issue Tracker.

Create your first issue

We will now create a new issue:

• Please navigate to your GitLab project overview page.
• Select Plan => Issues and click the New issue button:
  • Set the Title to My first issue. This is the minimum information required to create an issue.
  • Set the Description to These are the details of my first issue. You can use Markdown to format the description properly.
  • Set the Assignee to yourself.
  • Click the Create issue button to create the issue.
• On the issue details page you can change the issue description and other attributes such as the assignee. In addition, you can start discussions about the actual issue content.

How to write good issues

A good issue draws attention, has high information density and provides all details to get started with solving it.

• Be brief and precise.
• Use Markdown formatting properly.
• Provide all relevant details.
• If available, use the appropriate issue template. You can learn more about issue templates from the GitLab documentation.

Create labels and use them in an issue

Labels are a tool for the categorization of issues and merge requests. In addition, they are the basis for advanced planning features such as Issue Boards.

Now, we want to create two labels:

• Select Manage => Labels and click the New label button:
  • Set the title to Documentation and leave the predefined Background color.
  • Click the Create label button.
• Click the New label button again:
  • Set the title to Discussion and leave the predefined Background color.
  • Click the Create label button.
• On the label overview page, you can find the two defined labels.

Next, we want to assign the label to our issue:

• Select Plan => Issues to get to the issue overview page and click on the issue that you created:
  • Select the Edit button in the Labels property (on the right side).
  • Select the Discussion label from the selection list.
  • Click somewhere on the issue and the label is attached to your issue.
• Close the issue page and you can also see the attached label on the issue overview page. On this page, you can also filter your issue list. For example, you can filter all labels with a specific label by clicking on the label.

Example use cases for labels

Labels can be used for different purposes:

• Workflow-oriented: ToDo, Planning, In Progress, Review
• Type-oriented: Bug, Fix, Feature, Maintenance, Chore, Documentation, Discussion
• Priority-oriented: Critical, High, Medium, Low
• Affected subsystems: Database, Web UI
• Expected difficulty: Help Wanted, Good First Issue

From issues to merge requests

Merge requests visualize the development progress on a specfic feature branch and form the basis for reviews. You can directly create a merge request from an existing issue. In this case, GitLab also creates the feature branch on which you can perform your changes and connects the issue with the merge request.

Merge requests have a title, a description, labels and a discussion area and look quite similar to issues at the first glance. However, they also provide different features to support reviews, the performance of automatic checks and different options to re-integrate changes to your main branch.

Same feature different names

Other platforms such as GitHub, Codeberg or Bitbucket use the term pull request for a similar feature.

Contribution workflow of the planets example

In the following, we describe a detailed version of the GitLab contribution workflow that we optimized for the planets example.

GitLab contribution workflow demonstration: Contribute a README

Before you try out the workflow by yourself, we want to demonstrate it using a concrete example!

Story: Two persons are working together on the planets project. One person feels that the documentation starting point is missing and proposes to add a README file. After both agreed on the necessity of a the README file, he/she contributes an initial version.

Live demonstration instructor notes

• It is not intended that the participants work along. Instead they should get a good impression of how the process looks in detail.
• Decide which instructor will take on which role.
• You can use the following issue details:
  • Title: Add a README
  • Description: We want to provide an initial README file which serves as an introductory page for the project.
  • Label: Documentation
• You can use the following content for the README.md:

  # Planets
  
  This repository contains notes about potential planets for migration.
  

The workflow assumes that two persons collaborate on a GitLab project in different roles:

One person is the Owner:

• He/she typically owns the GitLab project on which the changes are performed and decides on the direction in which the project will develop.
• He/she performs the review of the contribution and merges it into the main branch.
• He/she usually has the Owner permission in the GitLab project. You can learn more about roles and permissions in the GitLab documentation.

One person is the Contributor:

• He/she works on existing tasks or proposes his/her own tasks.
• He/she performs the main part of the contribution process.
• He/she requires at least Developer access to the GitLab project.

The following sections explain the process and the interactions between the different roles step-by-step. In this scenario, we assume that the contributor proposes an own task to work on.

Check that the contributor has access to GitLab project (OWNER)

The Owner checks if the Contributor has at least the Developer access in the GitLab project:

• Select Manage => Members:
  • Search the name of the contributor.
  • Check if the role is at least Developer.
• If the contributor is not in the list, you can add him/her by clicking the Invite members button.

In this workshop, the Contributor usually already has sufficient access to the project because everyone works in the same GitLab group.

Explain your intent (CONTRIBUTOR)

First, you need to describe your planned contribution by creating an issue:

• Navigate to the GitLab project overview page of the Owner.
• Select Plan => Issues and click the New issue button:
  • Set a good focused title.
  • Provide a good description.
  • Select suitable labels.
  • Set the Assignee to yourself.
  • Click the Create issue button to create the issue.

Afterwards, you should reach out to the Owner to agree on the proposed task and the relevant details.

Doing the work (CONTRIBUTOR)

Once you have agreed on how you want to tackle the task, it is time to do the actual work.

Create the merge request

In the following, we create the merge request on the basis of our issue:

• Click on the Create merge request button on the issue page.
• The dialog shows the name of the feature branch that GitLab will create. Usually, you can keep the proposed name and proceed by clicking on the Create merge request button. Please note that if you proceed, GitLab will directly create the feature branch.
• In the next dialog, you specify the merge request details. GitLab reuses information of the underlying issue to prefill the form. In addition, it marks the merge request as Draft to avoid merging partial work. You can keep the proposed details and add yourself as the Assignee.
• Click the Create merge request button to finalize this step.

So far, you set up your working area.

Make the changes via the local Git repository

In general, you could make the changes using the GitLab Web interface or a local Git repository. We want to make the changes via a local Git repository. However, we still have to retrieve a copy of the Owner’s Git repository.

For this purpose, switch back to your Git shell:

• pwd - Make sure that you are not in your own planets Git repository. If this is still the case, you can use cd .. to switch to the parent directory.
• git clone <URL Owner repository> - Clones the Git repository of the Owner on your local computer. It creates a copy of the remote repository and automatically sets up everything to properly “communicate” with the remote repository. Similar to the push, fetch and pull commands, the clone command requires network access and needs to authenticate with GitLab. You can retrieve the URL of the Owner’s Git repository by clicking the Code drop-down menu and the Clone with HTTPS copy button on the GitLab project overview page of the Owner’s GitLab project.
• cd planets-<Owner name> - Changes into the cloned repository. Please make sure that you changed to the correct Git repository. For example, git log should show the usual history but the commit information should be different from yours.

Now, we can do the work on the prepared feature branch:

• git switch <feature branch name> - Switches to the feature branch.
• Do required commits using the “Modify - Add - Commit” workflow on the feature branch to fulfil the task.
• git push - Pushes the commits to the remote feature branch.

If you have made all changes and pushed all commits to the (remote) feature branch, you are done with this step.

Request a review

Now, it is time to request a review from the Owner:

• Navigate to the merge request page.
• Make sure that you have pushed all commits by checking the Commits and Changes sections.
• Indicate that you finished your work by clicking the Mark as ready button.
• Assign the Owner as reviewer by editing the Reviewers property to request a review from him/her.

Congratulations, you have successfully prepared the contribution!

Review the contribution and merge it (OWNER)

You can review the contribution by examining the changes using the Commits and Changes views. You can ask questions or propose improvements by using the comment features.

You can finalize your review by clicking on the Your review button on the merge request page:

• You can decide between different options depending of the results of the review:
  • Select Approve if your are happy with the proposed changes.
  • Select Request changes, if there is some rework to be done by the contributor.
• Click the Submit review button to conclude your review.

In practice, it will usually need some review cycles until the contribution is approved. In this case, the Contributor improves the contribution as requested in the review and will ask for a follow-up review.

Good practices for reviews

Particularly, when performing reviews, sticking to a good review practice makes the difference between reviews being a dreaded nuisance or a valuable team experience. We recommend Philpp Hauer’s blog post: “Code Review Guidelines for Humans” as a starting point for this topic.

If you approved the contribution, you can merge the changes into the main branch by clicking the Merge button:

• The merge request switched to the status Merged (Code => Merge requests).
• The issue has been closed automatically due to the Closes #<Issue ID> keyword as part of the merge request description (Plan => Issues).
• The merge operation has been performed by creating an explicit merge commit (Code => Repository graph).

Congratulations, you have successfully reviewed and merged the contribution!

Update your local Git Repository (CONTRIBUTOR)

After the changes have been merged on the remote Git repository, you have to update your local Git repository:

For this purpose, switch back to your Git shell:

• git switch main - Switches to the main branch.
• git pull - Pulls the changes from the remote Git repository.
• git branch -d <feature branch name> - Removes the local feature branch.
• git fetch --prune - Cleans up references to no longer existing remote branches.

Congratulations, you have successfully completed the full workflow!

Team exercise: Contribute information about Venus

Now, it is your turn to try out the contribution workflow practically!

Your task

• Find a team partner.
• Decide in your team who will take on the role Owner and who will take on the role Contributor.
• Perform the contribution workflow at the example of contributing information about Venus. You have about 60 minutes for this task. If you have some time left, you could switch roles and further experiment with the process.
• You can use the following issue details:
  • Title: Add information about Venus
  • Description: We want to collect some basic information about Venus.
  • Label: Documentation
• You can use the following content for the file venus.txt:

  Venus is full of love
  Wolfman will appreciate the absence of moons
  

Team exercise instructor notes

Before the exercise:

• Decide on a suitable method to divide the participants into pairs of two.
• Make sure that there is suitable way that the teams collaborate depending on how you run the workshop.

At the beginning of the exercise:

• Briefly summarize the task and answer open questions.
• Explain how much time the participants have and where to meet after they have finished the exercise.
• Explain how the participants can reach the instructors in case of questions.
• Start the exercise by dividing the participants into pairs of two.

During the exercise:

• Make sure that at least one instructor is approachable for questions.
• Ask the teams whether they need help or have questions about 15-20 minutes after the participants started to work.
• Tell the participants that the end of the exercise approaches about 5-10 minutes before the end of the exercise.

After the exercise:

• Ask the participants for feedback about the exercise.
• Answer open questions.

Key points

• A contribution workflow is important for efficient team work because it standardizes how changes to the repository are planned, agreed upon, made and checked.
• The typical generic GitLab contribution workflow consists of the following steps:
  • Create an issue: An issue sets the context of the contribution and supports discussions about the solution options.
  • Create a merge request: The merge request creates a feature branch to do the work and supports discussions about the actual solution.
  • Decide whether to merge or not: Make sure that the changes are fit for integration because they are added to the work basis of everyone.
  • On the basis of the planets example, you could try out such a workflow in detail.
• You can use the planets workflow as a basis for your own projects but we recommend that you optimize it to fit your specific needs.