Github Issue Templates: A Look at the New Issue Templates

Transcript

Hi, my name is Stu and on this channel we break down different technologies into easily digestible chunks. In this video we're going to do something a little bit different today and I'm going to take you around how I've personally set up a set of repositories of mine to use the new GitHub issue templates.

GitHub issue templates have been around for a fair while but they've recently updated them to add some new functionality. They've released them into kind of a beta state at the minute, so you may see this on your GitHub UI, you may not. What we're looking at here right now is how I've got one of my work-in-progress projects set up to have different categories of issues depending on what I think is going to be necessary. First of all we have a bug report: we think we found a bug in the machine, this is the place where people go. Next, if there's a cool idea that people have about my project they can go to the feature request area. Providing my repository has a security policy they can also view that, or they can have a link to the discussions.

So let's take a look at the first one and how I've got it set up. This is our bug report. First thing we do is we say to the user "thank you for taking the time to report the bug, I'm sorry that you've had this issue." As per normal, users can fill in the title so I can say "my test bug." We can provide them a set of handy links should they need it and then we provide them clear text boxes to provide information about what happened, what the steps are to reproduce, and anything else that we should know. We can make certain fields required or not required depending on the context of our project and the type of issue form that we're creating. This provides us a major advantage over the current globally available implementation which is listed with markdown comments that are often ignored.

If we take a look at our feature template we can see that we've got something slightly different. Again I have the helpful links but I've also included a checkbox to ensure that the contributors to my project have read and understood the project code of conduct. One other feature that I've recently discovered, which I didn't quite realize you could do, and you could do for some files but not for issue templates, is you can actually place them inside of the .github folder of a GitHub repository and this will be replicated across all of the repositories inside of that organization.

So let's take a look in a bit more detail at some of this configuration. We're going to start off with the config.yml file. That you saw there on line 1 we have blank_issues_enabled. This basically tells GitHub whether or not to enable blank issues. When this option is set to true, users have the ability to create an issue without any kind of template. This is something that you may or may not want depending on the context of your project. Next we have the contact_links section. Now this area is for you to put one or more links that appear on the new issue page. We'll go back to the new issue. This is what appears down in this bottom section for general discussions and the like.

Next if we switch across to another one of ours, let's take the feature request. Notice that the extension is now .yml, not .md as it was before. We can provide a name and description and a default title as well as labels of our choosing before starting to configure the body of the form itself. Typically from what I've seen in repositories that have implemented this beta feature already is they have a markdown section at the top giving a brief overview of what this form is meant to be used for, plus some helpful links. As we saw in my feature request earlier, you can see that I have a checkbox, also known as a checkbox in the issue template world. I provide a description for it and I ensure that the checkbox has actually been checked. Next I'll provide them a text box area for them to tell us all about the idea that they have. Provide them a nice handy description about what kind of things I expect to see in there. Again for this part, which is slightly different to this section above, I do also require this field to be filled in. And lastly I provide another text area for them, but this time it's just anything else that we think they should know: system information, version information, and such. But this time I do not require it.

My bug report is basically the same. I change the default icon that appears on the title, change the default label. Other than that I try and keep my forms very simple with a markdown area at the top to describe what this form is about, followed by one or maybe two text areas where people can put in their information. The full details of how you can go and configure these issue templates yourself will be linked in the description below.

If you enjoyed this video, consider subscribing to the YouTube channel for more content like this.