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:

• Bug #1 – doesn't have enough information, just a screenshot of the suspected problem and a line of text that vaguely describes it.
• Bug #2 – has multiple screenshots of CI output and VS Code windows, but nothing else.
• Bug #3 – has a clear description of the problem and a minimal reproduction. The submitter has thoughtfully included all relevant information pertaining to the issue.

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 #

• Be courteous and responsive
• Search for existing issues
• Provide all the information necessary to reproduce the problem
• Provide a minimal reproduction when it makes sense
• Taper your expectations — many maintainers do this for free!

Don't #

• Include information that doesn't pertain to the bug
• Include multiple bug reports in the same issue
• Be rude to maintainers or anyone else involved
• Spam the maintainers with follow ups
• Point fingers or blame others — it's just not productive

Just for Fun #

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