How to maintain a healthy issues list
Maintain an open source project can be hard, being good coders isn’t enough, you must also be organized to manage the community around the project.
So far, I created two projects on GitHub with more than 9000 ★s (+19.000 and +9.000), they both started as simple projects without particular claims, but fastly grew up reaching these numbers.
To make your project grow, you must listen to your users and address the problems and concerns they rise.
This can be particularly difficult if the list of issues grows uncontrollably. To avoid this problem you have to define some rules, and enforce them.
Issues template
First, create a .github/ folder, and inside it create an ISSUE_TEMPLATE.md and a PULL_REQUEST_TEMPLATE.md. These files will give you the ability to provide templates that the users will have to read and complete in order to send an issue or a PR.
To make the issues template useful, an important thing is to require the user to provide a reproducible example of the problem he’s facing.
For web based projects (JavaScript, HTML and CSS), you can prepare a pen with codepen.io and ask the users to edit it to reproduce the problem.
For problems that can’t be reproduced on codepen, you may want to ask for a GitHub repository with the minimal amount of code needed to reproduce the problem.
Along with this request, you have the opportunity to ask more informations to the user, feel free to ask them all the info you may find useful to reproduce and debug the problem.
For example, this is the template I use on one of my projects:
Thanks for your interest in contributing to Popper.js!
Please, make sure to fill all the sections of the template before submitting any issue.Issues without the required informations will be closed.----------------### CodePen demoEdit this CodePen to allow the contributors to easily reproduce your problem.
http://codepen.io/FezVrasta/pen/wGqJEz### Steps to reproduce the problem1.
2.
3.### What is the expected behavior?Describe what you would have expected.### What went wrong?Describe what went wrong.### Any other comments?Any additional information.
When you create the template, you have to take in consideration how much you need feedbacks from your users.
You need your community
If your project is new and has just few stars, you must make the community around it larger. This is needed because without an user base and enough feedbacks, your project will never grow.
You need your users, they are the ones that use your project and talk about it with their friends. Without them, you could even avoid to publish your code. The community, in an open source project, is the most important thing. Without it, your project is nothing.
This means that initially, you will have to be less strict with the management of the submitted issues. You need feedbacks, you don’t receive a lot of them, just take everything comes and try to manually clean them to make them easier to organize and read.
Once your project grows and you start receiving a lot of issues, your priority will be to filter the bad feedbacks and keep only the good ones. Here you will want to strictly apply the rules and summarily close the issues that don’t respect the requirements.
I have a premade reply I insert in any issue I close that doesn’t respect them and I use to kindly thanks the user for his feedback and ask for a better quality feedback the next time.
Thank you for your issue.
Unfortunately I can’t answer to all the reported issues without a little help from you.
Please, make sure to follow the issues template when you submit a new issue, in this way I will already have all the informations needed to understand the problem and help you with it.I’m closing this issue for now, but feel free to open a new one making sure to follow all the instructions!
Thank you for your understanding.
As you can see, I try to be kind, because the user spent time to report the problem he faced. But I also firmly explain that I can’t help him if he doesn’t help me first.
Label the issues
Labels are invaluable to make it easy and fast to read the issues list and decide where to focus.
They are useful bot to you, and to the potential contributors that want to help with your project.
Prepare a good set of labels that can help you to categorize the issues, you may want to have labels to identify the part of app that is afflicted by the problem, to know if it’s a bug, a feature request or an enhancement of an existing feature.
Good practice is to create a “Good first bug” label that can be used to label the issues that can be easily addressed by new contributors. This will help them to pick a good issue and get confident with your code base.
Referring again to one of my projects, I have a “Core” label I use to identify the issues related to the core of my library, a “Modifier” one I use to identify issues related to a particular plugin I ship with the library and a “Docs” one to label the issues that ask for better documentation or for problems with it.
These are some of the methods I use to keep my issues list clean and healthy, if you have more advices please let me know replying in the comments!
