So - you want to open an issue on an open source project.
As a maintainer of a few large-scale open source projects including Node.js and Electron, I've seen my fair share of issues - some so lovely I want to give them a hug and others so awful I can feel my eyeballs burning. Now, I'm going to share some of the things I've picked up on over the years so that your friendly local maintainer will want to hug you for every issue you open too.
In the open source world, your communication style is going to form the basis of the first impression a maintainer has of you - how can you leverage that knowledge to help make it the best impression possible?
Starting Out
Ok, so you've found a bug in a library you're depending on for your project, and you want to report it to that library. This totally blocks progress on your project, so it's important to you that it gets fixed. What do you want to think about as you go to report that bug?
My approach to this is basically: "make this issue as easy as possible to triage and solve". What does that even mean? Let's talk about it.
1. What does a good issue on this library's repository look like?
If there's a template, you should ensure that it's filled out to the fullest of your ability.
Neglecting to fill out an issue template both ruffles maintainer feathers and results in them needing to ask you for more information - delaying any potential fix.
Many projects have unique issue culture and style; it may not be familiar or instinctive to you, but taking those few extra minutes is worth it if it allows you to meet the maintainers where they are. It's likely that a maintainer will also be able to take a look at your issue more quickly if it's delivered in the same style as that repository's typical issues.
2. Have you provided a way for the maintainers to reproduce this issue locally?
As a maintainer, my ability to triage an issue is at its most effective if I'm provided with enough information to take actionable steps for reproduction. With no actionable steps, I'm forced to make educated guesses, which may harm my ability to understand the underlying causal pathways of the bug. I may also miss a crucial setting that triggers its appearance if I'm not aware of its relevance to the issue at hand. Sometimes this won't be possible, and that's not the end of the world! Just do your best.
Some examples of this include making your own repo someone can clone down and run, using an online IDE like CodeSandbox, creating a GitHub gist, or creating a fiddle in the case of Electron.
3. What information might a maintainer need to fix this?
Do you have screenshots? Rad. Include them. A crash dump? Throw that in there too. As a general rule, as long as you feel that it might help give a maintainer context, more information is always the way to go.
There's always going to be some degree of friction when interfacing with maintainers about a bug, since they don't have access to all the information living inside your head. The best you can do is try to oil the issue's surface so that you reduce that friction as much as you can. If they ask you for follow-up information, try to respond in a reasonable amount of time so that the issue doesn't enter a blocked state. They want to help you as much as you want them to help you!
4. Are you yourself willing to work on this bug?
It's not an expectation that you be willing to work on a bug you're reporting, but it provides good signal for the maintainers as they work to understand your perspective and potential willingness to chip in so they can best guide you.
The way I respond to an issue opener will differ pretty significantly depending on if I see they want to help fix the issue. If they do want to help, I'd give them some contributing primers and try my best to point them in the right direction & offer guidance as they proceed. If they're just reporting, I'd just work to provide status updates on the bug as they occurred, and make sure to let them know when a fix was on the horizon.
An Issue from Poor to Excellent
What does the above look like in the real world? To make this a little more concrete, let's start with an eyebrow-raising issue and progressively transform it into something a maintainer will be much more grateful for.
This is pretty useless to me - a user is clearly having a problem, but I'm not even sure that the problem is, let alone where I might start to fix it.
I'd need to follow up several times here, which disincentivizes me to spend time on this issue and makes it less likely to get fixed quickly.
This is a little better! Now I have a better concept of what the general issue is, but I still don't have a great idea of what "incorrectly" means to you. Definitely more work that can be done here.
Big improvement! I now have a complete understanding of what the user expects to see, what the user is seeing, and a helpfully provided screenshot to confirm the behavior.
This issue is now as low-friction as it gets. I can see the bug, understand what the user wanted vs saw, and it's also clear to me what the user did leading up to the bug, which makes it so that I can effectively and quickly reproduce that bug on my local machine.
Wrapping Up
There's no single best way to open an issue on a project, but keeping these general principles in mind as you continue to move through open source spaces will hopefully allow you to grow more comfortable navigating them and working to shorten the feedback loop on your bugs as you find them.
Concisely, I recommend the following for your future issue endeavors:
- What did you expect to have happen?
- What actually happened?
- Can the maintainer reproduce this?
- Did you answer all questions?
Feel free to leave me feedback either on this post or via Twitter about any other key components of effective OSS issue composition or things you think might be important to consider here!
Top comments (0)