As the word gets out about your open source project, people will start to try it out. And at some point, people will open issues. Congratulations! When an issue is opened, it means someone out there cared enough to report a bug, ask a question, or make a feature request. This interest is a good thing for an open source project.
But if your project becomes very successful, the influx of new issues can start to get overwhelming. In the following sections, we cover some tips on managing incoming issues.
1. Labeling issues
GitHub provides a default set of issue labels when you create a website.
» bug
» duplicate
» good first issue
» help wanted
» invalid
» question
» ready for review
» won’t fix
You can manage these labels by going to the Issues tab and clicking the Labels button. Make sure the set of labels makes sense for your project. Assigning labels helps you manage issues as they come in.
2. Triaging issues
As new issues are created, it’s important to triage issues. The word triage comes from the medical field. Merriam-Webster defines triage as “the sorting of patients (as in an emergency room) according to the urgency of their need for care.”
Triaging issues is similar to triaging in a hospital. Triage, when applied to issues, is the process of reviewing new issues and assigning labels to indicate what type of issue are they (bug report, feature request, and so on.), determining their priority, and assigning issues to people. In some cases, you may close issues you don’t plan to address during triage.
Every triaged issue should have some label applied. If necessary, you can even create a triaged label for this purpose. Assigning a triaged label to issues that you’ve triaged makes it possible to see all issues that haven’t yet been triaged by using the unlabeled filter, as shown in Figure 10-11.
To maintain a sense of sanity, it often makes sense to schedule triage on a regular cadence as opposed to doing it all the time as people create new issues.
3. Issue templates
It would be great if everyone who submits an issue understood how to write up a proper bug report or if they understood what makes for a good feature request. A bug report that just says “Your stuffs is the broken” is not too helpful to the repository maintainer.
To help foster good issues, you can set up issue templates that guide people filing issues on your repository to supply the information you need.
In the Settings page for your repository, in the Issues section in the main pane, is a big green button labeled Set up templates. Clicking that button takes you to a templates setup page where you can choose from a set of pre-existing issue templates or create your own, as shown in Figure 10-12.
From the templates setup page, follow these steps:
- Select both the Bug report template and then select the Feature request template.
You should see them listed on the page. Note they’re not yet active. They still need to be committed to the repository.
- Click the Propose changes button to enter a commit message for these templates, as shown in Figure 10-13.
- Click the Commit changes button to commit these templates to the repository.
They are stored in a special .github/ISSUE_TEMPLATE folder. If you navigate to that folder, you should see two files, bug_report.md and feature_request.md. Take a look at the contents of those files to understand the structure of an issue template.
You can create new templates by going through the previous steps or by manually adding a file to the .github/ISSUE_TEMPLATE directory with the same basic structure as the existing issue template files.
Now, when someone creates an issue on your repository, they first see a set of issue templates, as shown in Figure 10-14.
Clicking the Get started button on one of the templates then displays the issue creation form, but with the contents prepopulated with the template information. Figure 10-15 shows an issue prepopulated with the default Bug report template.
The contents of the issue walks the issue creator through all the information expected of them. Of course, the person creating the issue can always choose to ignore the template and put anything they want in the issue.
4. Saved replies
Often, as your repository grows in popularity and the issues start to flow in, you’ll find yourself repeating responses over and over again. For example, if someone reports a bug, you may need them to supply a log file. If every bug report should include a log file, then you should mention that in an issue template.
But even if you do, many folks will forget to include it. This situation is where a saved reply can come in handy. A saved reply is a canned response you can use over and over again.
As of this writing, canned responses apply only to a user and are not specific to a repository. So you can create your own saved replies, but they will not immediately be available to other members of your repository.
Go to https://github.com/settings/replies to manage your list of saved replies. To create a new saved reply, fill in the form at the bottom, as shown in Figure 10-16.
To access the saved replies when responding to an issue or a pull request comment, click the arrow in the top right corner of the comment box, as shown in Figure 10-17. That brings up a list of your saved replies. Click the one you want to use to fill the comment box with that reply.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.