Quick tips to enhance your gitlab issue workflow, part one
Gitlab logo
This post is originally posted on i-Logs blog.
When Emmanuel Bergmans and myself started i-Logs back in 2009, we were using a simple workflow based on Subversion (now Apache Subversion) and Mantis. In 2016, we moved all our projects from subversion to git, the new kid on the block. At the same time, we adopted Gitlab CE as our end-to-end software development platform. We use Gitlab for version control, source hosting, issue tracking, code review and continuous integration. That was the main reason we adopted Gitlab (and git) over subversion: it provides us with an integrated tool for managing sources and all the development activities in one single place. How convenient is that ? The purpose of this post is to introduce quick tips we have adopted to customized the Gitlab CE issue tracker to our needs. Initially, this article is written for our clients as a kind of public documentation of our internal processes but we sincerely hope you'll find something useful if you are also using Gitlab. We are currently using Gitlab 12, so all the tips presented in this post refer to features available in that version.
We assume you have an access to a gitlab instance and you have at least a minimal knowledge of the features provided.
In this post, you will cover the following topics:
- how to define and use label categories
- how to define and use group labels
- how to define and use star labels
This post is the first instalment of a series of two. In a later post, we will cover how we are dealing with the issue board which is an important part of our daily workflow.
A side note: Gitlab uses the Issue metaphor but we, at i-logs, usually talk about change requests. We believe that the word "issue" has a negative connotation and that not every change request is, well, an issue per se. Through this document, we will preferably use the term change request although in Gitlab, it is called an issue.
Categorize labels
For one of our client, we have an average of 300 open change requests distributed on four different projects. Using label categories help us sorting these change requests more efficiently. We have identified the following categories: priority, pile, type, environment and velocity. To illustrate our point, we will focus on the first three.
Priority labels define which change requests matter the most in terms of attention. To keep it simple, we have three different priorities: low, medium and high. Low change requests are the one we will eventually handle someday. High change requests on the other hand requires an immediate attention. Most of the change request are labelled as Medium.
Piles defines the current state of a change request. It is immediately related to the board feature of gitlab (more on this in our next installment covering the use of the development board).
We also recognize 4 different types of change requests: new features, small enhancements, bugs and questions. A new feature is an important change either in terms of amount of code required or changes in the user experience. A enhancement represents a small change or a minor improvement. We are talking about a bug when a functionality of the software does not work as expected. We apply the question label when the request does not imply a change in the functionalities of the software.
Label categories is not a feature provided by Gitlab out of the box. The good news is that you can name your label exactly the way you want. Practically speaking, we define a label category by using a common prefix to all labels belonging to the same category. Prefix are separated from the label name by a colon. The label itself is written in capital letters.
Try to choose a short but meaningful name for the prefix in order to avoid having long name for labels. For instance, we use the pri: prefix for priority. So we have the following labels defined for priority: pri:HIGH, pri:MEDIUM, pri:LOW. We are using the type: prefix for type label category, which includes type:ADD for new features, type:ENH for enhancements, type:BUG and type:QUE for questions. We are using pile: , well… for the pile one, vel: for velocity and env: for environment, etc
When to use label categories?
Label categories are useful when one
- defines a new change request,
- review an existing change request
- search for specific change requests
When adding a new change request to a project's issue tracker, label categories help us improve the definition of the change request. As mentioned above, we have a total of 5 different categories, we want one and only one label of each category to be added to the change request as a kind of meta-data. It means that for each change request, we have to specify its priority, its type, its velocity, its state and the impacted environment. Note that the pile remains undefined. It will be used when the change request are sorted.
Because Gitlab issue tracker is both powerful and flexible, we can easily implement this "one label mandatory per category" rule. Unfortunately, and to the best of our knowledge, we have no way to make this rule mandatory. In the end, it is really a matter of internal process and self discipline.
Using label categories will also force you to use the same scheme everywhere. If like us, you deal with several projects, always using the label categories scheme helps us define efficient habits. Adding a new change request? Done with its description? Specify its type, pri, env, vel and you are good to go.
When reviewing a change request, the meta-data and the pile helps us understand almost immediately what kind of change request we are looking at. That's another added value of using label categories. Take the below example:
A properly defined change request
Just by looking at the above list of labels, you know the change request is a bug (type) severely impacting (priority) the production environment (environment). The fix for that bug is estimated to be an easy one (velocity) and is currently ready to be tested (pile). By always using the same categories and labels, we create a habit for both our customers and for us.
The latest advantage of using label categories is when searching for change requests. Here are few examples, using the search bar of the issue list:
- Wanna know which change requests requires your immediate attention? Go to the Issue list and use the following filters:
type:BUG,env:PROD,pri:HIGH… - Your customers is running out of budget and want a release with quick wins (also known as cheap change requests with great benefits)? Use the following filter:
type:ENH,type:ADD,vel:1,vel:2 - etc
Issue list filtered for urgent matters
Make use of group labels
If you have several projects hosted under a single instance of Gitlab CE, we strongly advice you to use the project groups. Project groups can be seen as a common namespace for projects and team members. Among other things, this feature allows you to group projects (obviously), deal with users access, have a consolidated view on the activities, merge requests and issues.
By default, each project has its own set of labels. If you have several projects, you have to define labels within each projects. This can be a cumbersome and prone to error task and a waste of time, particularly if you use the same set of labels among the different projects. For instance, we, at i-Logs, have a default set of 24 labels (see above) and currently around 20 active projects. Do the maths and you'll get the picture.
Defined once, used everywhere
One of the convenient thing with project groups is that it allows you to define group labels which are then automatically available in each project belonging to the group.
To define a label at the group level:
- select group from the top level menu;
- select a group;
- on the left side menu, select the Issue entry and the Label entry;
- from the empty list, click the create label at the top right corner of the screen.
If you already have a label created at the project level, you should be familiar with the group New Label form as they are identical.
The first advantage of a group label is that it is automatically available in all child projects. Time saved !
This is not the only advantage. Within a project, you can use a group label exactly like a label created directly in the project. But there is more: you can use the group label on the group consolidated information. For instance, you can filter the consolidated list of issues in a group of projects with one or more group labels. Also you can subscribe to a group label to receive a email notification when a new change request is added to the Issue list of each project belonging to the group. Imagine having four projects in a group and the type:BUG label defined at the group level. If you subscribe to that label, you'll receive a notification email for each bug defined in any of the four projects.
To receive notifications for a specific label, simply go to the list of labels and click on the subscribe button to the right of the corresponding label. This is valid for both group and project labels.
A few words of advice on project groups:
- you should carefully think about your global projects organization before starting because although Gitlab makes it possible to move groups and/or projects, it can have unwanted side effects.
- Choose your label names carefully. At the project level, Gitlab does not let you create two labels with the same name. Nevertheless, you can create at the group level a label having the same name than an existing label at the project level. You'll end up with duplicate label names in that project and it can lead to confusion.
Use Star labels
In each project, from the label list view (Issues -> Label), you can star one or more existing labels. Star a label to make it a priority label. From the prioritized labels list, it is possible to order the labels to change their relative priority.
We star the priority labels
At i-Logs, we star all the labels from the pri: (priority) category. Once stared, we order the labels from HIGH to LOW. This little trick is very convenient when using the issue list by ordering the list by priority.
Order the change request list by priority
Please note that although it is possible, in a project label list, to star a label defined at the group level, as the time of writing this post, it is not (yet?) possible to star a label at the group level.
That's it for today. I really do hope you have learn something interesting. If you have some tips do not hesitate to share them with us. For my part, I'll be back shortly with another post covering how we deal on a daily basis with the issue board. Stay tuned !