How to File a Bug Report

They say there's no such thing as bug-free code. When problems arise, creating a minimal reproduction will give you the best chance of a speedy resolution.

When a potential bug is discovered, many developers' first reaction is to file an issue. That's great, but please exercise due diligence before posting! Have you reviewed the docs to confirm the behavior in question? Are you able to reproduce the bug outside of your app? Have you removed all unrelated code to make sure nothing else is causing the problem?

I get it — creating a reproduction takes time! Why should that be on you if the bug is upstream? The thing is, the process of creating a minimal reproduction will often uncover the problem and, in many cases, the problem will be in your own code. I know that sounds arrogant but, as an open source maintainer, I see it happen quite frequently.

Help Us Help You #

That's not to say our libraries don't have bugs…they totally do! We're just asking you to help diagnose the problem before we spend hours diving into your code only to realize it's not something we can fix in our code.

If you're using our software, we've already provided some kind of value to you. It's not fair to ask us to troubleshoot your app. Maintainers generally want to eliminate bugs from their software, but triaging issues can be a painstaking task, especially in larger projects.

Even if your bug report is completely valid, an issue that lacks sufficient information — or has too much of the wrong information — can easily fly under the radar for many reasons.

Think of it from a maintainer's perspective. You wake up in the morning to three new bug reports:

Which one would you be most willing to resolve first?

Better Bug Reports #

Here are some tips to help you get results faster. Investing a bit of time up front will usually lead to a more positive result. After all, there's nothing worse than watching your issue collect dust.*

Do #

Don't #

Just for Fun #

In case you were wondering, here's how maintainers tend to feel when various bug reports are filed. 🤣

Bug Reports chart

*Unfortunately, some maintainers are simply unresponsive. In my experience, the majority of open source authors care about their projects and want to be good stewards. Sometimes it can help to offer a bounty or, better yet, a PR. Alas, I've seen really good PRs collect dust too. In that case, you might need to consider forking the project or finding an alternative.