I’ve created and maintained several open source projects over the years, and my biggest annoyance with them is bug reports. Not bugs themselves. Those are inevitable, and the actual process of fixing them is interesting. But bug reports are another matter. Far too often, I get reports that are all but useless. They waste time and cause frustration for everyone involved. In the hope that I can reduce this, I offer some guidelines for writing good bug reports.

The goal of a bug report is to make it possible for a developer to reproduce the bug. I cannot emphasize this enough. A developer who can reproduce a bug is halfway to fixing it. At that point, they can bring their entire toolset to bear: debuggers, profilers, test cases, and lowly (but useful) printf()s. Inversely, trying to fix an unreproducible bug is an exercise in futility. Often, one ends up flying blind, reduced to changing code based on hunches and guessing. Believe me, it is not fun.

So how do you make it easier for devs to reproduce a bug? Developers know the software in question, but your computing environment is a complete mystery to them. The more they know about that, the easier it will be for them to reproduce the issue. With this in mind, reports should contain information such as:

• The exact operating system version. (e.g. OS X 10.10.5)
• The version of the buggy software. (e.g. Chrome 44.0.2403.130, Sublime Text 3 Build 3083, ag version 0.30.0, etc.) It’s not uncommon for users to report bugs that have been fixed in newer versions.
• Steps to cause the problem. Exact commands are very helpful.
• Exact error messages. Codebases can be searched for exact error messages. Not so for paraphrased ones.
• Debug logs. Again, copied exactly.
• Any unique data involved. I can’t convey how infuriating it is for someone to say, “It breaks on this file.” and not provide the file.

Err on the side of including too much. It’s quite rare that I read a bug report and think, “Wow. This is way more info than I need.” Also, overcommunicating helps to reduce back-and-forth. Every reply/response cycle decreases the likelihood that a dev will get to the bottom of the issue.

Guidelines are good, but I find examples help more. I don’t want to single anyone out, but here are some examples of bad bug reports. If you see your name on one of those issues, don’t feel upset. Reporting bugs is a skill. It doesn’t come naturally. Just try to do better in the future.

• After installing, don;t have tools on path · Issue #3 · ggreer/dsniff
• #BUG in diacritic · Issue #1 · ggreer/jekyll-gallery-generator

What am I supposed to do with these? They don’t even describe what the problem is, let alone how to reproduce it. On the flip side, here are some good bug reports:

• Doesnt work with build from outside the source directory · Issue #18 · ggreer/jekyll-gallery-generator
• Ag thinks this PDF is not a binary file · Issue #637 · ggreer/the_silver_searcher
• Cannot run ag in parallel · Issue #33 · ggreer/the_silver_searcher

These are pretty close to ideal. They include everything needed to reproduce the issue. One even linked to an example file that caused the bug. The limiting factor for fixing these was me, not the reporter. That is how it should be.

Writing good bug reports requires more effort, but the payoff makes it worthwhile. Remember this when clicking, “Create Issue” and not only will you make developers’ lives easier, but you’ll improve the likelihood of getting the bug fixed.