6.2. How to work with issues

6.2.1. Introduction

First, it is recommended to read this interesting article from GitLab's blog about issues: Always start with an issue

What this article says in introduction is the key principle why any development shall always start with an issue: Before you begin anything else, summarize your ideas in an issue and share it. Its such a simple rule, but the impact is huge!

6.2.2. Theory

The goal of an issue is to write down your idea of the task you want/need/have to work on in order to open a discussion with your colleagues to clarify open points, and at least to detail why you want to do this task and how you intend to do it, so that you can argue later on if any discussion arise about this feature/fix/etc.

Some reasons why an issue needs to be correctly filled are listed in the above article:

  • You may not know everything there is to consider.
  • There may be parts of the system you arent familiar with.
  • There may be limitations or possibilities youre not aware of.
  • There may be factors for users you may not know.
  • There may be work going on in a parallel effort which relates your idea.

However, as also mention in the article, there are times where you don't need to create an issue. When you need to do some small corrections or typo fixes for example.

"We have to be practical, as with most rules, there are reasonable exceptions."

6.2.3. Practice

Some examples are provided in this GitLab tutorial "It's all connected"

6.2.3.1. Issue creation

In practical, you need to create an issue for every task you are working on, using the left panel menu "Issues". The title and description shall be written in English, as everything else in GitLab.

6.2.3.1.1. Label assignation

Then you need to assign Labels to your issue in order to filter them easily with the Issue Board. For internal usage at ERTOSGENER, we use different type of labels, which are described in a dedicated internal Wiki page: Please refer to it (if available) and fill in the appropriate label for the 4 available types:

  • Area
  • Type
  • Priority
  • Status

6.2.3.1.2. Due Date

There is also the possibility to set a Due date to your issue. The Due date is used by GitLab to remind you by email one day before that you need to finish your task. This date can also be used as search criteria, and todo list.

More information are provided in the GitLab Documentation

6.2.3.1.3. Milestone

If Milestones are available in your GitLab instance, you can specify it to your issue so that planned your activities and filter issue per milestone in GitLab using the left panel Issues=>Milestones.

6.2.3.1.4. Epic and Weight

It is possible to specify an Epic and a Weight for an issue, but this requires the "Starter" version of GitLab for the Weight and the "Ultimate" version for the Epic.

These fields are useful when you work with AGILE methodology.

6.2.3.2. Reference your issue in your commit

Once you have created your issue, you shall refer to it in every Git Commit you will perform for the designated task, using #'issue-id': tag in your commit message. This is important so that you can trace every commit to a task and find the problematic commit which caused a bug for example.

6.2.3.3. Issue Board

The Issue Board is a simple way of visualizing and changing each Issues' status: you can drag the issue in the correct status column of the Issue Board. This allows you and your colleagues to know exactly what is closed, what is ongoing and what shall be done without having to dig into each issue.

Here is an article which described many ways of using the Issue Board: 4 ways to use GitLab Issue Board