Written by Eva Maciejko, full-stack Web developer for Gologic
Gitlab is extremely useful for creating and managing issues. In four points, let’s see how easy it is to document the entire evolution of an issue, so that anyone looking at the issue can quickly grasp its status.
Take the example of issue ABC created today with number 55.
Labels: change in status
Labels allow us to categorize an issue according to various criteria. For example, several sets of labels can be used together to describe a priority or status, or how an issue relates to a particular project. Let’s say our ABC issue belongs to project PO028, its status is To do and its priority is P3. It will then have these three labels. When an employee starts the job, he or she only has to change the issue’s status (label) from To Do to Doing. For example, Gitlab makes it easy to sort issues by tags and quickly identify all issues in progress.
Time tracking: estimated and actual times
Gitlab provides two time measurements related to the issue. The first is the estimate, which is the expected duration of an issue. It can be entered by typing in the comments box:
/estimate 1w 2d 1h 15m
/estimate 4h 30m
(w = week, d = day, h = hour, m = minutes)
By pressing the Comment button, the /estimate command is understood by Gitlab, which will then enter the estimated time in the Time Tracking space (in the right sidebar of an issue). To delete an estimate, simply type:
The second measurement is the actual time spent on a issue. This is specified by the /spend command in the comments box:
/spend 2h 15m
Gitlab will then raise the Time Tracking progress bar to show where the issue is in relation to the estimated time.
Comments: inflection points
Comments in a Gitlab issue are valuable markers of its status. Issues, questions, additions, any kind of inflection point that changes the course of the issue, should be included. Gitlab even allows you to enter a list of tasks that can be checked when they are completed, a useful element to illustrate the progress of the issue. You can also add images by simply copying and pasting them in the comments, a great way to quickly document changes to be made or a bug that requires fixing.
References: linking commit messages to issues
Gitlab provides a way to link commits with an issue. To reference an issue in your commit, just use the pound sign (#) followed by the issue number. For example, let’s say we have the following commit message:
Progress of issue #55.
Gitlab will automatically add a small message in the comments of issue 55, linking this issue with this commit (see the SHA commit code referenced in the issue). However, it becomes even more interesting once this issue is completed. Let’s look at one of the following patterns (default patterns) in the commit message that completes the issue:
closed issue #55
closed issues #55, #56
closing issue #55
fix issue #55
fixed issue #55
fixed issue #55
fixing issue #55
Gitlab understands that the issue(s) is(are) resolved. So when this commit arrives – directly or by merge request – in the master branch of the project, Gitlab will automatically close the referenced issues.
Note that this pattern can be changed by a Gitlab administrator, see https://gitlab.com/help/administration/issue_closing_pattern.md
It is valuable to use the issue reference (ex: #55) consistently throughout commits and descriptions of other issues (for example in Issue 62 I refer to #55) since Gitlab recognizes it and displays it as a link.
Gitlab offers a multitude of ways to better document and link issues. We have explored four very simple ways to make day-by-day workflow management more effective.