Issue tracker¶
An Issue tracker is an important part of any code repository. It is the component where planning, execution and follow-up meet.
In GitLab each repository has an Issue tracker built in. The additional benefit of this tight integration is that you can link and interact with issues from other events. For example:
- You can link to the test job that uncovered a bug directly from the description of the Issue that is reporting this bug, making it easier for the programmer that will be fixing the bug to immediately have access to the relevant context.
- You can automatically close a reported issue when committing the fix using git by adding
Fixed #{id of the Issue}to your commit message (by default this only works on the main/master branch!). The Issue tracker will add a link to this commit for you, so you can easily track which part of the code was causing troubles and what the solution was.
It is a good practice to always create an Issue when finding a bug or when defining a feature request as this will add a lot of traceability to the development process. When working in a team, the comment section of an Issue is also the ideal place to discuss changes or possible approaches.
Creating an Issue¶
To create an Issue, go to the Plan > Issues tab on the left side of your project page. If the Issues page is not already pinned for quick-access, we advise you to do so now. When you click on New issue you will see the following form:
Enter a short descriptive title for the Issue. Some people prefer to prefix the title with an indicator of the type of issue, e.g. [BUG] or [FEATURE]. This can be handy, but know that you could also use the Label system instead (which is more flexible as you can easily add and remove multiple labels).
Use the Description to add relevant details to the Issue (e.g. steps to reproduce the issue, in case of a bug report). Use Markdown to format the description and make it easy to read. Markdown is a lightweight markup language with a plain-text-formatting syntax. An interactive tutorial explaining the basics can be found here. To be more specific, GitLab uses GitLab Flavored Markdown: a superset of Markdown. More info on it's capabilities can be found here.
You can also switch to rich text editing by clicking the prompt in the bottom bar of the editor. This mode will change your Markdown into rich text immediately so you can check your syntax without manually clicking the preview button. You can switch between rich and plain text mode anytime.
An Issue can be assigned to one or multiple project members (this is especially useful when working in larger teams).
Finally, the Issue has some (optional) project management related attributes such as the Milestone it belongs to (helps with planning), the Weight (indication of the amount of effort required to resolve the Issue) and Due date.
Labels¶
Each issue can be assigned one or more labels (cfr. tags) which can be used to organise issues (e.g. you can click on a label to discover other issues in that category). Labels can be defined at a project level (by you as the project owner) or a group level. When clicking on the label selector (new Issue form), you will see that some labels have been preconfigured:
These labels were added to facilitate communicating with us using the Issue tracker: it helps us to maintain an overview of all the issues where our help is needed and to quickly find and evaluate Lab reports.
| Label name | Purpose |
|---|---|
| Assistance needed | This label allows us to easily differentiate between Issues you've added for personal tracking, versus the Issues you are addressing towards us. Always add this label if you need input from us! |
| Report | Your lab session reports should always be labeled with Report. |
| Lab 1 - 5 | When requesting assistance or labeling an Issue as a report, also label the Issue with the appropriate Lab label. This makes it easier for us to filter Issues. |
Assistance needed? When to ask for help¶
Posting an Assistance needed issue when encountering a problem should not be your first instinct, always try to resolve it yourself first:
- Read the assignment again, did you miss a critical step?
- Go through linked documentation.
- Do your own searching, there are millions of developers that have encountered similar issues as you have. Answers are out there.
Even if these extra steps don't resolve your issue, they will help you formulate your problem better.
Issue writing do's and dont's¶
Writing clear and concise issues is a very important skill, which mostly requires the author to put in a small amount of effort. When you write a good issue description and provide us with adequate information we can provide better answers. Below we will list some do's and dont's to keep in mind:
- Give your issue a descriptive title!
- Don't share screenshots of code, errors, logs, terminal sessions, job outputs, etc unless you have no other option. Rather copy the relevant text into a code block with syntax highlighting.
- Add syntax highlighting, by specifying a language next to the backticks before the fenced code block.
```javaas the start will highlight all contained code as java for example, most languages and syntaxes are supported, use the right one! - Using a code block allows anyone to copy-paste the text to either start a new internet search or open the source code of GitLab and involved components to look for the origin.
- When you think it is helpful to see the code block in its “natural” environment (e.g. a IDE, frontend, etc.), please attach both a code block and a screenshot.
- Add syntax highlighting, by specifying a language next to the backticks before the fenced code block.
- If you have a problem with a CI Job, provide links to relevant job runs, so we can quickly navigate them.
- Provide steps to reproduce erroneous behavior you have encountered and be specific! If you followed certain internet guides, provide links to them.
- Mind your spelling, grammar and formatting. Make use of titles, lists, indentation, etc. to structure your issue, so it is easy to read.
Tip
You can even link to your source code in an issue, if you post the URL of the file and append #L<linenumber>-<linenumber> (for example
https://gitlab.stud.atlantis.ugent.be/devops-public/devops-project/-/blob/main/src/main/java/be/ugent/devops/services/logic/Main.java#L7-9), it will open the code in GitLab and highlight the selected block.
When you view files on the Web version of GitLab, you can select lines and shift-click to select a range, the URL will change appropriately and you will be able to copy paste it into your issue.
Quotation of issues¶
As mentioned in How are the lab sessions quoted? your use of the issue tracker is also taken into account for your personal score. But don't be afraid to ask questions, we mainly want to see that you have put effort and thought into your issues and that you have at least tried to resolve the issue on your own with research and critical thinking!
Issues with lacking descriptions such as "Our code is broken" paired with a screenshot of a java exception stacktrace will not do. These type of issues typically also get ignored in open source projects, some are even actively closed when they do not follow guidelines.