How to Report a Bug

If you use software, you'll encounter bugs. Sometimes software does the wrong thing, or doesn't anticipate what you want to do with it.

With open source software, it's easy to write to the software developers who write applications and libraries. But communication is an art, more than ever. A good bug report includes the right information, in the right place, and with the right tone. Here are some tips for how to write a bug report that will make both you and a software developer happy.

Table of Contents

  1. Specifically say what is wrong
  2. Include information about your browser and configuration
  3. Use a bug tracker
  4. Search for & subscribe to existing issues
  5. Provide an example, if you can
  6. Please be nice, developers are busy people with feelings
  7. A great bug report, for example

Specifically say what is wrong

It's broken…

When you report a bug, it's because something is wrong. Writing simply that software is 'broken' or 'crashes' doesn't give a software developer enough information to fix it. A great bug report specifically says what you tried to do, what you expected, and what the software did instead.

I added 2 + 2 in my calculator.
I expected it to give me a result of 4.
Instead, it gives 5.

"It Crashes" is not a good bug report: it's like telling a doctor "it hurts" without specifying how, when, or where. Crashes have many distinct varieties that you can distinguish by using more and better words. For instance, "the browser tab crashes with a sad face icon" or "the browser tab becomes unresponsive" or "my computer crashes". Descriptions like these, that replace the ambiguous "it" and use a more specific word than "crashes", help get issues fixed.

Include information about your browser and configuration

Sometimes software works in one place, for one person, but doesn't somewhere else. Your operating system, browser, and other installed software all has some impact on the bugs that crop up.

Include basic information about your setup to make issues easier to debug. If it's a web-based application, include:

For installed software and libraries, there are some other things to report:

If it's a web application, you can be extra nice by opening up your browser debugging tools, seeing if there's an error in the Console, and reporting it exactly, by copying & pasting the text.

Use a bug tracker

If the project has a bug tracker, like GitHub issues, JIRA, or Phabricator, report the bug there, and there alone. Developers will be notified and respond.

If you aren't sure that what you're seeing is a bug, don't ask whether something should be working or should be broken - just report it in full, and the developer will follow up with clarifications.

Search the bug tracker first for the issue you're going to report. Active projects will often have a long discussion already started about exactly the issue you're running into.

When you find an issue, the first thing you should do is to click the notification button. This will subscribe you to the thread, triggering email updates when someone posts back to it. Never post +1, 'Any progress?' or other sorts of pressuring comments to threads.

Provide an example, if you can

If you find a bug in a library, like a jQuery plugin or kind of module you use in your own software, try to provide a minimal example or testcase that demonstrates the bug.

You can create a GitHub Gist to share a longer code snippet, or if your bug is best demonstrated with live HTML, JavaScript, and CSS, services like JSFiddle and codepen make it possible to create an example that actually runs on the web.

The key to creating examples is making them as small and focused as possible. Isolate the bug's behavior from any other code and technology in your application so that it's immediately clear what the issue is and maintainers can quickly run the example.

Please be nice, developers are busy people with feelings

This is broken - I spent hours debugging it!

Maybe the bug ate your homework, or it's taken you hours to track down the culprit and the bug is something really silly, something that nobody would ever do. It's okay to be personally annoyed, but don't take your anger out on another person: nobody deserves abuse.

Many open source projects have adopted a Code of Conduct to make their norms, rules, and responsibilities explicit. If a project uses a code of conduct, review it first before drafting your first message.

And while a bug may be critical or preventing you from finishing a project, it's not useful or appropriate to insist a developer prioritize it. They may have other issues that are far more important, whether professional or personal. If an issue is truly urgent, you may want to hire someone to fix it, or try to fix it yourself.

A great bug report, for example

This bug report for GitLab.org is perfect: it gives specific steps to reproduce the issue and says exactly what behavior was expected and what behavior occurred.

polite.technology is a free text under the CC0 license originally penned by Tom MacWright