Issue templates

[Isabellagarf]

What is an Issue template?

Kourtney taught me this feature the other day and we thought it would be worth sharing! Github has a feature where you can create a template for issues submitted on your repositories, allowing more structured responses. Kourtney has a repository with lots of different examples here. If you click 'create new issue' you can see all the different template options she has set up for this repository. Here is a link to her code for these templates. These templates are created in yml files.

Example screenshot below

Key features

Issue templates have a lot of features you can add if desired. You can create drop down options, spaces for folks to describe specific issues, automatically link issues using certain templates with repo admins, specific github projects, and labels. This is especially beneficial if you are expecting a high volume of issue submissions to report bugs, request feature access, report instrument damages, etc. I can see many creative ways to use this.

How to create an issue template?

Here is a really good link that helps you walk through the steps of creating your own issue template. It provides an example yml code for different template feature examples that you can modify.

Tips

I got stuck on a few steps while trying to figure this out, so I am going to comment my work-arounds here.

.github/ISSUE_TEMPLATE folder creation

This folder likely doesn't already exist in your repository, so you need to take some actions to get Github to make this for you. I did this by going to: Settings - scroll down to 'Issues' (Under 'Features') and clicking 'Set up templates'. Click any template from the drop down menu and click 'propose changes'. This action will automatically create the ISSUE_TEMPLATE folder in your .github folder. From this step, I opened my repo locally, deleted the template I just made (which I believe is a markdown file, and is not what we are looking for here), and created a yml file in the same folder.

To create a new YAML file in Rstudio...

look under the 'Files' tab on the right, and click the 'New File' drop down. Click 'R Script' - when you are naming the file, replace the .R at the end with .YML, and this will automatically turn this into a YAML file. This is where you can copy the YML issue template script from the website I linked above.

[Kourtney-Burger]

To add to this, you can create issue templates or issue forms. Templates are markdown documents (.md) and look like a text file when you create a new issue. Forms use yaml syntax (yml.) and are fillable when you create a new issue (the example above are all .yml).

You can also choose how your templates are displayed when users open new issues by creating an accompanying configuration file (config.yml). This file can do things like remove the option to create a blank issue (blank_issues_enabled: false) or link to external sites (contact_links:).

In this PAM-Glider example, you can see the last issue template includes an autodirect link back to our main website and directions to create a blank issue for unresolved questions.

Another way to set up how your issue templates are displayed is to change the order of them when you create a new issue. You can number your template file names to control the order they will appear (they are listed alphanumerically and grouped by file type)

[Kourtney-Burger]

Another use case for issue templates is to track progress on a certain project or task. For incoming glider data, we have created issue templates for each glider type and pam system combination. Each one has a unique set of data pre-processing tasks so these templates help the analyst track their progress and automatically assigns other team members and tags