Issue Templates

Welcome to Tanuki Tuesday, where I look at the features offered by GitLab. This week I'm going to look at issue templates, and how they can help guide users through providing the right information to diagnose issues.

Have you ever had meaningless bug reports? Do they make you wonder how many more times you have to tell someone that you need to know the steps they took to get the issue? Or the browser they were using at the time? Or, well quite frankly anything to make a useful bug report?

It is frustrating.

But, there's a way to resolve this, and guide users into providing the right information at every juncture. Issue templates.

What Are Issue Templates

They are predefined layouts, a questionnaire of sorts, which can be selected when creating an issue within GitLab. If they exist in your repository then, when you create a new issue, you get the option to "Choose a template" prior to the description box.

Once a template has been selected, the description box will be populated with the content of the template ready for completion.

With headings and/or questions in place, people logging issues will know exactly what information needs to be provided.

Creating Issue Templates

Issue templates are written in markdown. They exist as .md files within your project repository. Create a template in the .gitlab/issue_templates folder (you may need to create the folder first) and, once it is on your default branch, it will be available when creating new issues.

The templates use Gitlab Flavored Markdown, which is an extension of standard Markdown. They can contain comments, which allow links to resources and other information which would otherwise be white noise if it were on every issue. Comments are hidden from the preview and rendered displays, and are just use HTML comments e.g. <!-- this is a comment !-->.

My Users Won't Select a Template

Users are lazy. I know, I am a user still. But there's a way around that. Actually, there's at least two:

1. Set a default template in the project settings
2. Create a link to the "new issue" screen, which has the template name in the URL e.g. https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal The template name for the issuable_template variable needs to be properly escaped in the address bar, so space becomes %20.

Why Use Issue Templates?

Aside from the obvious reason of guiding users to provide the correct and relevant information, it allows you to specify different requirements for different issue types. Not all issues are created equally, and therefore you may need different information to be able to categorise and allocate issues properly.

Bugs will need the minimum steps to reproduce. It may also require the version of the application, operating system information as well as the expected behaviour. It may be prudent to request screenshots of the issue to show what the user was seeing.

A new feature will require different information to a bug. Information about the desired behaviour, business rules which need to be applied, and even why the feature is needed as a justification of even planning the feature. I have a project which asks whether there's examples of a similar feature from which inspiration can be drawn. It can help engineers visualise the concept better, and see what the user was thinking about when they made the request.

Some templates may be more specific. An issue template for something which is Technical Debt will need to know the specific area(s) of the system the technical debt impacts, and may even request input for a solution. As these are likely to be raised by a developer or someone with intimate knowledge of the area, more specific and details answers may be provided which may not be possible from someone raising a bug.

Issue templates allow the use of quick actions as part of the template. These allow relevant labels to be assigned, so a bug might get the label Bug to be allocated, and any default associated labels; whereas a feature request might be labelled New Feature so it can be distinguished from bugs without needing someone to set the label specifically after reading the issue. The quick actions can be used to assign the issue to a person or people (depending on your subscription level). That can then be used to ensure the right people are reviewing the issue at its creation point, and removes the need for someone to triage and allocate issues.

Getting Started with Issue Templates

It's not always easy to know what to include in a template. For that reason, I've created a small repository of issue templates which you can use, either as they are or as a base for creating your own. To see them in action within the New Issue screen, fork the repository to your own GitLab account, and create a new issue for it.