Bug Reports

Overview

This is a quick primer on how to write good bug reports.

Before you write a bug report, make sure you know what you're reporting.

The basic pattern is to describe each of the following:

1. What you did (the actions)
2. What the program did (the behavior)
3. What you expected it to do (the expectation)
4. Everything that might have affected the behavior (the environment)

It's amazing how often people assume that a developer knows one of these three things or even just says "this program doesn't work for me". Details, please.

Also, please report if this happened once or if this happens every time. It's much harder to debug something that doesn't happen every time.

Details of the bug report sections

The Actions

Tell me what you did. Exactly. Don't say "I ran the program", say "I used the command line program -with some args exactly.

The Behavior

Tell me what the program did. People often leave this out. Yes, yes, it's really good that I know you wanted the program to make your eggs over-easy but it really helps when I know that it burned down your house instead.

The Expectation

The flip side of the behavior: Yes, the program burned down your house, but what did you expect the "-torch-dwelling" option to do? Oh, you expected it to torch your neighbor's house. Darn. My bad.

I need to know what you wanted it to do -- sometimes this points to a flaw in my own thinking or in my documentation.

The environment

Here's the tricky one -- I need to know everything that might have affected the run. At the very least:

1. What version of the program were you running
2. What platform (OS, version, patches) were you running it on.

Other things might be good to know. For example, if the program has an external dependency (such as the rsync-backup program does) then I need to know about that dependency (e.g. the version number of rsync.)

Beyond that it's a judgement call. For example, I normally don't care about what type of file system it's running on, unless you do some experiments and find out that type of file system matters. I also don't usually care about how big the file system is or how much RAM you have -- except when you're at 0% free space.

A good rule here is: when in doubt, put it in.