A GitHub Issue Template for Your Projects

Updated: 2019-03-02

Now that we have some example pull request templates, we might as well create an issue template for our GitHub projects.

Table of Contents:

  1. Creating an Issue Template for Your Project
  2. My Template
  3. Example Template File
  4. Further Reading

Creating an Issue Template for Your Project

Similarly to a PR template, it's super easy to setup an issue template for your project. Create a file named ISSUE_TEMPLATE and place it one of three locations:

  • The root of your project
  • .github folder
  • docs folder

An extension is optional, and GitHub supports Markdown (.md). I've chosen to create a Markdown template so you can use features like Markdown formatting, @-mentions, and task lists.

Once GitHub detects the ISSUE_TEMPLATE file, it will auto-populate new issues with the contents.

My Template

My issue template is much simpler than my PR template. I try to prompt users for the basic information I always need for new issues:

  • What behavior were you expecting?
  • What actually happened?
  • How can I reproduce it?
  • What was your environment like?
    • Firmware versions, host environment, hardware versions
  • Do you have any logs?

I've also added a Prerequisites section for projects with external issue contributors. This section prompts users to run through some basic steps before filing their issues.

If you only have private projects, feel free to remove the Prerequisites section (as I do for my own projects).

# Prerequisites

Please answer the following questions for yourself before submitting an issue. **YOU MAY DELETE THE PREREQUISITES SECTION.**

- [ ] I am running the latest version
- [ ] I checked the documentation and found no answer
- [ ] I checked to make sure that this issue has not already been filed
- [ ] I'm reporting the issue to the correct repository (for multi-repository projects)

# Expected Behavior

Please describe the behavior you are expecting

# Current Behavior

What is the current behavior?

# Failure Information (for bugs)

Please help provide information about the failure if this is a bug. If it is not a bug, please remove the rest of this template.

## Steps to Reproduce

Please provide detailed steps for reproducing the issue.

1. step 1
2. step 2
3. you get it...

## Context

Please provide any relevant information about your setup. This is important in case the issue is not reproducible except for under certain conditions.

* Firmware Version:
* Operating System:
* SDK version:
* Toolchain version:

## Failure Logs

Please include any relevant log snippets or files here.

Example Template File

You can find an example implementation file in templates GitHub repository. The ISSUE_TEMPLATE_example.md file contains the example template shown above. To use this file in your own project, copy that it into your project. Make any adjustments to these templates to suit your needs.

Further Reading

Change Log

  • 20190302:
    • Improved grammar
    • Added table of contents
    • Updated links to point to template repository

Related Articles