Issue templates

An introduction to issue or user feedback templates for new Open Source project or community managers.

This guide is an introduction to issue templates in an Open Source project. While this guide is customized to GitHub, the advice provided here is general and can be applied to other collaboration platforms that offer templating. By the end of this guide, you will have a basic understanding of why issue templates are important and how to set up effective templates for your project. This guide is complementary to an agile or scrum workflow, if your team already uses one of these methods of project management.

The following topics are covered:

  1. About issue templates

  2. Case study: TeleIRC

  3. Additional resources

1. About issue templates ðŸ”—

Issue templates are a common feature of GitHub, GitLab, and other git forges. They allow you to pre-populate a new issue with template text. Issue templates can also automatically apply an assignee or label to a template, depending on the type of feedback it is. Some common issue templates in Open Source projects may look like the following:

  • Bug reports

  • New feature requests

  • Improvements to existing functionality

These are three common templates, but your project may use more or less depending on the unique context of your project. Issue templates are effective tools to structure new feedback and save time in the Open Source development life-cycle.

See the official GitHub documentation for issue templates to learn more about using issue templates on GitHub.

1.1. Why? ðŸ”—

Issue templates are helpful for both newcomers and core team members in your community. Project newcomers benefit from extra guidance and prompts on what to include in their reports. They might be asked to provide specific information, like what version of the application they use, what web browser or operating system they use, and so forth. It also saves core team members time in reviewing new feedback from the community. The necessary information is provided in the original comment; you do not have to follow-up and ask for more common information.

Issue templates are not always useful in the earliest stages of an Open Source project. However, they are a strategic tool to scale participation in your project as you grow your community. Over time, you will invite more people to participate in your Open Source code, whether it is end-users, customers and clients, academic researchers, or grassroots activists. Issue templates help you engage a community in the earliest stages of growth in an Open Source project.

2. Case study: TeleIRC ðŸ”—

To demonstrate how issue templates work, we will look at the TeleIRC project. TeleIRC is an Open Source back-end application to connect Telegram groups and Internet Relay Chat channels together. TeleIRC uses issue templates to structure different types of feedback from developers and end-users. Take a look at the four templates available in the project:

Four issue templates available for the TeleIRC project.

The following screenshot shows an example of a reporter using the "bug report" template to report a bug:

Screenshot of a TeleIRC bug report completed using the issue template.

These templates are used to quickly diagnose problems, discover interests in new features, and cut some of the chase out of troubleshooting. Find the exact templates used by the TeleIRC project in their .github/ folder.

3. Additional resources ðŸ”—

Updated on 19 Sep 2022