Filing an issue is not about delegating your problem to another developer, it’s about helping maintainers solve issues they haven’t encountered yet.
Since it’s in your best interests these issues get fixed ASAP, let’s see what are the most common best practices to help others developers help you.
- insult the maintainer or the project by any mean: nobody has time to read how frustrated you are in using something you probably never even donated a cent for, but that makes your project, or daily work, possible
- open an issue without a detailed description of what is the problem
- provide just a screenshot of a stack trace, or a screenshot of the error without describing how you managed to encounter such error
- demand extra efforts on your behalf from the maintainer, including cloning whole repositories to reproduce such issue, requiring tools of any kind that are not already used by the project itself, or show code that wouldn’t reproduce out of the box the issue, due indirection created by your own stack (transpilers, bundlers, usage of different programming languages, or platforms not officially targeted by the project)
- file an issue that is already known, already opened, or already documented as caveat, known limitation, etc. Do read and search before, don’t file issues impulsively.
- be kind, never forgetting the maintainer doesn’t owe you anything, even if you donated for the project, ’cause that doesn’t enable you to be mean
- provide as many details as possible, including your Operating System, the browser that you used at the time the issue manifested, or the environment that caused such issue, if not Web related, and the third parts libraries involved in your own project, or the used tools that potentially might be responsible for such issue (transpilers, bundlers, usage of different programming languages, or platforms not officially targeted by the project)
- provide a minimal test case able to reproduce the issue … yes, you should invest time in recreating the issue within the smallest possible test case that would easily confine moving parts of the software stack, so that such issue won’t become some sort of ghost hunting for the maintainer. Big plus if you have an online page (CodePen or anything else similar, possibly named, or titled, after the issue, for search-ability reasons)
- if the issue is purely visual, provide one or more screenshots able to quickly identify what is the visual part that is not rendered as expected
- be sure you’ve read the documentation and everything you did, before opening the issue, follows best practices, avoids known caveats or limitations, and doesn’t violate common programming best practices
If you happen to have a clue where the issue could be in the source code, please link to that part so that the maintainer would have at least a possible starting point to investigate. In my experience, such initial hint rarely reveals the real issue, but it often helps having a basic clue in what, where, or why, the issue reaches that part of the code.
In an ideal world, the labels “good filed issue” or “good first issue” shouldn’t exist, while the “bad issue” one, should negatively score any developer that doesn’t follow these simple rules (just 5 don’t and 5 do, it should be easy to handle for everyone), similarly to what Stack Overflow, or other platforms, do with the reputation.
You don’t want to collect “bad issues filing” reputation, ’cause the next step could be being muted, ignored, or even banned from repositories.
If you’ve followed all the suggested do, but the maintainer didn’t respect you by any mean, try to find alternatives to that specific project, as nobody wants to deal with assholes, and hopefully this post would help reducing them in the wild.
I haven’t put any specific link or blamed anyone in particular, because I’d like to use this post, keeping it out of any publication, as reference in every occasion I feel people should read it first, and I hope you’ll do the same to help the Open Source community keep growing, ignoring people that don’t deserve to be part of it, either as users, or maintainers.
Happy Open Source to you all ♥