Tips to successfully build your open-source projects #7. Manage the issues
After releasing and promoting your project, you can expect some people to start playing with it: congrats!
The flip-side of success is that your users will open some issues on your repository for various reasons: bug reports, questions, suggestions, …
Receiving your first few issues can make you feel anxious, especially if these are reporting bugs: keep calm, everything is fine! If your project does not have any issues, then maybe it’s because no one is using it. So, receiving bug reports is, in some way, a good sign: some people cared enough to try your project and spent the time to report an issue as they want to keep using it!
Categorize & Prioritize
Issues on an open-source project is a very broad concept. I personally don't really like the term issue as it implies that there is a problem with your project.
The reality is a bit different and people will open issues on your project for various reasons: bug reports, questions to get something working, questions to understand how something is implemented, feature requests, improvements ideas, … Even for bug reports, some bugs may be due to an incorrect use of your project, or your project may not be related at all.
Thus, as you can see, an open-source issue may cover very different topics, and it may be more appropriate to refer totickets rather than issues .
Having that in mind, it is important to categorize the incoming tickets. You should at the very least consider these three categories: bugs, questions, and feature requests. After receiving a few issues, you may want to include additional categories: real bugs, bugs due to misuses of your project, security issues, documentation improvements, …
Different tickets may be more or less important. A security issue most likely requires more immediate attention than a feature request. Additionally, you may not be able to solve each ticket right away: some tickets may remain open for several months, meaning that you will eventually have multiple tickets opened at the same time. Taking the habit to categorize each ticket you receive will greatly help you to better manage and prioritize them.
Regarding prioritization, I believe it is up to each project owner to decide how to prioritize each ticket and each category. I tend to respond immediately to questions or misuse of projects because they are fast to handle, for example.
Collect information
It can be very stressful to receive a bug report for your project: you spent a lot of time building and testing it, and yet, a user you never met before encountered an issue with it. It personally took me some time to get comfortable receiving and treating issues as I tended to feel bad about it: it's one thing to ship buggy code to production at work, it's another to deliver buggy code for everyone to see on an open-source project!
With experience, I noticed that many issues reported by users are not actually coming down to your code. The user may have installed your project incorrectly. Or the issue may be caused by the user running your project with some unsupported dependencies versions. Maybe the user's own project has a bug and he wrongly assumed it comes from your code. Finally, he may even use an old version of your project and the issue is already fixed in a more recent version.
Usually, many people file a bug report without much context. Some just state that it crashes without even detailing their integration! Without enough context, you will not be able to determine whether the issue is really related to your project, and you will be wasting your time.
When a user files a bug report, it is his responsibility to include enough information for you to diagnose it. At the very least, a bug report should contain the following information for you to understand if the issue is relevant and how to reproduce it:
- What version of your project is used?
- What is the system running your project?
- What is the error?
- What is the expected behavior?
- Are there any relevant logs?
- What did the reporter already try to investigate this issue?
- Are there some steps or a small code snippet to reproduce the error?
If the issue does not contain enough details, your first action should be to ask the user for more details and to patiently wait for more information.
Take your time
When I first started to get bug reports, I started to jump into it in the few minutes after it was opened to be as reactive as possible. I was already stressed to be notified about a bug in my code, so I definitely did not want to make things worse by leaving an issue without a reply for too long.
However, many times, the issue reporter was coming back after a few hours to say it was coming from his code: I ended up wasting a couple of hours trying to solve a non-existent issue.
As mentioned in the previous section, you should always make sure to have enough information in the bug report to determine if the issue is related to your project or not. Doing so will filter many irrelevant issues, but there will still be some falling through the cracks: I tackle this by waiting one day to reply, except if it immediately appears as something wrong in my implementation. Many of the issues I received were closed by the reporter on the very same day.
Being reactive is important, but you do not need to be available 24/7: you are not paid, you are using your free time to build this project. Don’t be a slave to your own project. Of course, don’t let issues accumulate, that would appear as a red flag to new-comers. If you really don’t have time, put a disclaimer at the top of your README that you do not maintain your project anymore, that the project is not production-safe, or that you need the help of other contributors.
Set the correct expectations
If your project gets traction, you will start receiving issues worded in an unfriendly way. I would frequently receive issues with only the title filled: no description, no hi, or thanks. I always feel a bit disrespected by this kind of issue.
Dealing with issues can be exhausting and frustrating depending on the popularity of your project. Some people may put a lot of expectations on your work, especially if they started to use it in production. It's not uncommon to see open-source maintainers giving up on their projects after burning out.
I believe this part is quite important but frequently overlooked. Many people, including myself, started to open-source their projects without much expectation but got caught up once it became somewhat popular. They then felt trapped by their own project, spending a considerable amount of their time solving issues for others, including some people not being very considerate for the amount of work they are putting in.
One way to free yourself is to set the. correct expectations for others. You may first add a disclaimer on top of your README to state that this project is not production-ready and that you may not be able to address issues timely. If people still want to go ahead with your project, they at least know what to expect and you can deal with issues however you want.
Keep it clean
Always close your issues when you are done or if no user replied to you for too long. There is no point keeping your issues open if you addressed them, or if the reporter never got back to you to provide enough details.
Closing an issue might sound rude and I did not feel comfortable doing so at first, especially for questions where I simply replied with the answer: I’m technically done, but I was waiting for a day or two before closing it. Now, I just close the issue immediately when it is done while notifying the user that he can re-open if he feels the need.
Listen to your issues
When receiving issues, make sure to pay special attention to questions and misuses.
If you see one question getting asked over and over again ( how to use xxx? ,does your library support xxx?, …), it could mean that your documentation is lacking somewhere or not structured correctly, or that an important feature is missing and would constitute a huge improvement for your project.
Similarly, if you see people misusing a particular part of your library often, maybe you should improve the documentation or adjust the design of your project to make it less error-prone.
Don’t forget that only a few users will report issues that they encounter: many more might have encountered the exact same thing but did not report it. Even if an issue is reported two or three times, it is already a sign and you should think about why different people reported it. Even though the error might be coming from their end at first sight, if it keeps coming up, you might be able to help in some way.
Read all my tips to successfully build your open-source projects:
Originally published at https://cylix.github.io on September 9th, 2017.
