How to Write a Perfect Bug Report

- 4 minutes read - 794 words

Bugs are part of software, and so is bug reporting. Reporting well is a necessary skill in an ever-growing number of job titles. In this post, I’d like to explain how to write a perfect bug report.

What’s Perfect?

What do I mean by ‘perfect’? A perfect bug report allows the receiver to start meaningfully solving the problem.

Even on great teams, this isn’t always possible. However, you’ll find it’s commonplace on great teams.

A Template

Teams that are great at this tend to have either:

  • A bug report template that’s pre-populated
  • An HTML wizard to collect this information before submitting a bug
  • A culture of debugging excellence

Here’s a markdown template I’ve used:

### Steps to reproduce

### Expected behavior

Tell us what should happen

### Actual behavior

Tell us what happens instead

### System configuration

**Operating System**:
**Browser**:

Let’s look at each piece of this report.

Steps to reproduce are vital. What’s the setup, and what actions did you take?

Expected versus actual behavior comes next. The expected behavior is often skipped in bug reports, yet it’s crucial. If I’m not a consumer of the part of the application you frequent, I might not know what you expect to happen. Your expectation could be wrong, contain insider knowledge to your team, or expose other bugs that you’ve found ways to work around.

System configuration helps me start thinking about what the issue might be. If you’re experiencing zooming on an input, I expect that to be happening in Safari mobile. If you aren’t using Safari mobile, that’s useful information.

Attachments like images, video, and screen recordings are a major plus.

Here’s one of these forms filled out:

White Screen on Cart

### Steps to reproduce

Given I am not logged in
And I add a sweatshirt to my cart
When I click on my cart icon in the navbar

### Expected behavior

Then I see my cart with my sweatshirt

### Actual behavior

Then I see a white screen (screenshot attached)

### System configuration

**Operating System**: Windows 10
**Browser**: Chrome Version 102.0.500

Note: Seems to happen more during busy times.

Omit Severity

Some bug reports have a field to indicate the severity of the bug. Does this affect one person (low severity), a team (medium), or all customers (high)? What is the importance of the bug?

I suggest you omit this field from the form. In my experience, the person creating the report usually doesn’t know the actual severity. How could they? Even if the site is down at your location, without communication it’s nearly impossible to know that that is true for all users.

What happens when the severity is wrong? When it’s overestimated, it can create a sky-is-falling overreaction to bugs. When it’s underestimated, it can lead teams to de-prioritize important issues.

When an estimate is found to be inaccurate, we rarely update it, even when that mistake is widely understood. This leads people to tune out the estimate and it sends mixed messages to observers.

To summarize, severity is easy to get wrong, and being wrong creates another problem you didn’t have before.

Report What You See, Not What You Think

A suggestion I’d offer to anyone opening a bug report: report what you see, not what you think.

A practice that hinders a bugfix is latching onto the wrong solution early in the process. The guidance “I think that Sidekiq email jobs are failing”, especially from a senior engineer to a junior engineer, sends one down a particular road. It may be the wrong road. “This customer didn’t receive this email” is better because that is not a theory.

If you’re a programmer who’s certain you know what’s going on, jump on a pair programming session with the bug fixer and confirm that you’re right from first principles.

Counterarguments

“This feels like too much work!” you say. I get it. You didn’t earn an MBA or become an HR expert to write bug reports. It’s not part of your job description.

Unfortunately, software users find bugs that interrupt their work. To fix them, I have to know some things. If I don’t know them up front, I’m going to ask simple questions until I do. You’re saying a house is on fire; I need to know the street address.

And bad bug reports tend to resist fixing. Go to any bug reporting repository and look for the bug tickets that have been open for more than a few weeks. They’ll almost certainly be lacking one or all of the subheaders I described above. Sidestep this morass by providing the minimum information.

Conclusion

This has been my attempt to demonstrate a perfect bug report. In summary:

  • Follow a template
  • Omit severity
  • Report what you see, not what you think