This accidentally shoe-horned its way into another post I was writing. It didn’t quite fit there, so I thought I’d pull it out into its own thing. It is as a result fairly brief.

This is in my opinion the correct format for submitting a bug. Deviations are possible, but if you are unsure whether or not you should follow this format you should probably follow this format. If you are unable to conform to this bug format due to not having enough information or not having the time to acquire all of it, you can submit a truncated form, but bear in mind that the maintainer probably has less time than you do because they’re having to deal with all the other truncated bug reports people have submitted and is likely completely unable to obtain the information that you could obtain with a little extra effort.

Subject:

When I <DO STUFF> <THING HAPPENS> instead of <THING THAT SHOULD HAPPEN> (variants permitted)

Body:

I did this thing (be reasonably detailed. A sequence of precise steps is helpful here. the shorter you can make it the better, but make it short by finding a short sequence of steps to reproduce, not by eliding details).

This is what happened.

What I expected to happen was this.

(If appropriate) I have attached a file which recreates the problem

(if available) Here is the exact error output from the program

(if you have got everything else right first) Here is what I think might be happening

Salient features

• The bug report contains enough information to reproduce it. Granted some bugs cannot be reliably reproduced. In this case, say “when I do this, this sometimes happens”. Most bugs do not fall into this category. I’d say even most bugs you think fall into this category don’t fall into this category.
• The bug explains why the experienced behaviour is not what you expected. This allows the maintainer to easily distinguish whether the bug is in the software or in your understanding of the software.
• The main portion of the bug report is purely factual. It does not speculate as to causes. It says “This happened. I expected this to happen instead”. You are welcome to speculate as to causes after you have done this, but front load with the information the maintainer actually needs. They are better placed to figure out the cause than you are. If you start with speculation then you are at best making them work harder to find out what the problem in your bug report is and at worst you are sending them down a false trail.

Why should you do this? Well, because it will make the maintainer’s life easier of course, and out of respect for your fellow human beings you should always strive to do that.

Not a good enough reason? OK, fine. Try this one:

People who develop software are doing many different things. They’re working on new features, responding to bugs, they probably have other things on the go. Unless you are literally their top priority (and even if you think you should be, you probably aren’t), or they have the patience of a saint, they will spend a finite amount of time working on your bug until it’s fixed or they give up. This means you want to control three things:

1. What that amount of time is
2. The percentage of that amount of time spent working on the bug rather than on your bug report
3. The probability that this process will terminate in “the bug is fixed” rather than “they give up”

How do you do this?

You do the first one by inclining them kindly towards you. You can do this in a single bug report by making it as useful as possible. A history of good bug reports will do it even more effectively.

A good bug report will also maximize the amount of time spent on the bug rather than the report because it is clear, does not elide details, and does not make you hunt amongst a sea of speculation for the salient features.

A good bug report will also maximize the chances of success: The clearer and simpler you can make the problem, the easier it is for the maintainer to identify what’s actually going wrong and fix it.

Also, as a bonus, developers can usually distinguish between a bug report that is likely to waste their time and a bug report that is likely to be useful fairly quickly. If nothing else, bug reports likely to waste their time come from people who have previously tended to waste their time. When prioritising, which do you think they are likely to look at first?

So. This is how to submit a good bug report, and why to submit a good bug report. I bequeath this knowledge to you. Use it wisely.