How to write a bug report

Here are some brief thoughts on writing good bug reports in general.

Main elements

There are four crucial elements when writing a bug report:

  • What did you do
  • What did you see
  • What did you expect to see
  • Why did you expect to see that

What did you do

This is sometimes called "Steps to reproduce".

The purpose of this part is so the person trying to fix the bug can reproduce it. If they can't reproduce it, they probably can't fix it.

The most common problem here is not enough detail.

To help avoid that, it's a good idea to write this as though the person reading it knows nothing about the application or site that you ran into the problem on.

Use words like "typed" and "clicked", not "I did such-and-such task".

Say what you did, not what you meant. Use words like "typed" and "clicked", not "chose" or "selected" or "tried to".

Good starting points: operating system name and version, browser name and version, what URLs you visited (exactly), what you typed and clicked. Pretend you're walking someone through what you did.

Example:

I'm running Ubuntu 16.04.1 with Gnome desktop, using Chrome 54.0.2840.90 (64-bit).
I recreated this in a incognito window (no extensions).
I typed "https://www.example.com" into the address bar,
Then I clicked the "Help" link in the top right.

What did you see

This is the obvious bit to include.

Again, more detail is better. In particular, the exact wording of any messages - copy and paste if you can. A message that sounds generic to you might mean something very important to a developer trying to figure out the bug, if only they know the exact message you saw.

Focus here on exactly what you saw, and not on interpreting it. If it's relevant, provide screenshots, labeling them to match the steps for reproducing the problem. If the problem is an observed behavior, still try to describe it in terms of what you saw in each step, and not how you interpret what you saw. Or provide a video of the bug happening.

And if it doesn’t happen every time, be sure to say so, with a rough idea of how frequently you see it when you do the same things.

Examples:

After clicking "Help", a page loaded with URL
"https://www.example.com/about" and the title "About WidgetCo".

When I click the “Close” button, about one time in ten, the window doesn’t close.

What did you expect to see

This is often overlooked. It's surprising how often I get a report "the site did X" and my reaction is "well, the site is supposed to do X, what's the problem?" Then we have to go back and forth trying to figure out why the person submitted the bug report.

It's much better to include this explicitly, even if it seems obvious to you.

Example:

I expected to see a page with a title like "Help" or
"Using this web site".

Why did you expect to see that?

This is the other often overlooked part.

This can help save a lot of wasted time when it turns out that there's a typo in the documentation, or the user is missing some other part of the requirements, etc.

A documentation error or unclear requirements are just as much bugs as broken code, but it's nice to zero in on what the problem is sooner than later.

Did you expect to see "Y" because requirement 1.2.3 said it should happen? Was it on page N of version 2.1 of the user manual? Did the site help at URL xxxxx say something that led you to expect "Y"? Or maybe your officemate told you it worked that way.

Another benefit is that in trying to find an authority on what was supposed to happen, you might discover that you misunderstood something and what you're seeing isn't a bug at all. Or you realize that what you thought was an authority really isn't.

Example:

In my experience with other sites, links named "Help" go to
pages with help information for using the site, not pages
with information about the company.

Other comments (optional)

You can offer other information that you think would be helpful, but please do it separately from the previous elements - keep the facts separate from the opinions - and keep it concise.

Example:

This looks to me like it's probably just the wrong link.

Let me know if I can help test a fix or anything.

My wife’s cousin’s girlfriend says it might be the frangistan coupling.

Exceptions to the rules

None of this is carved in stone. For example, if starting the application caused my laptop to hang so hard that I had to power it down, I can probably omit describing what I expected to see and why.

More detail is generally better, but keep in mind that developers are human too, and probably won’t read the whole bug report carefully if it looks overly long.

General tips

Be very clear whether you are describing unexpected behavior, or asking for a change in behavior. Surprisingly, in some "bug reports", you can't really tell which the user means.

Some phrases that should probably never appear in a bug report:

  • XXX didn't work
  • XXX doesn't work
  • XXX needs fixing
  • XXX should do YYY
  • XXX looks wrong

Many applications and tools, and less often websites, have specific instructions on how they'd like bug reports to be submitted, what information is most helpful to include, etc. Look for and follow those instructions.

Don't be emotional. If you're really annoyed about some behavior that's blocking your work, that's perfectly understandable. But it'll be more productive to take some time to cool down, then stick to the facts in your bug report.

If you know that this behavior has changed - maybe this exact function worked for you in version 1.23 - then mention it in your comments. That kind of information is extremely helpful.

If you haven't tried this on the most recent version of things, try it there. It might already be fixed.

More

The most unique part of what I've described here is making sure to say why you expected what you expected. I know I saw that in a "how to write a good bug report" somewhere before, probably on the web, but it's been a long, long time. If anyone recognizes where that came from, please let me know in the comments.

Meanwhile, here are some other pages that seems particularly good, and go into more detail about various of these points.

Download Shipping Faster: Django Team Improvements
blog comments powered by Disqus

Success!

You're already subscribed