So you’ve hit a problem with your web browser or browser extension of choice, and you’d like to report the issue. Writing that up properly can be tricky. It can be hard to know where to start and which details to include. I’m someone who’s often on the receiving end of such bug reports, so I thought I’d write up a quick guide explaining what to include and why.

First of all, the goal of a bug report should be to make the problem clear and to help the development team reproduce the issue1. For that, they will need to know what happened, what should have happened instead, the steps to take to trigger the problem, and any relevant details about your device (e.g. browser version). Stick to the facts, keep it polite, and take your time to think through the details.

Here’s an example of a bad bug report:

You broke Dave's website, fix it!

It’s kind of rude, and it does not contain enough information for anyone to understand or reproduce the issue. If I received this bug report I might try loading my homepage in Firefox and think “Well, it works for me”. Unfortunately, bug reports like this are mostly a waste of everyone’s time.

Here’s an example of a good bug report (for the same problem):

# Environment
- Windows 10 (version 22H2), Edge browser (version 116.0.1938.81)
- DuckDuckGo Privacy Essentials browser extension (version 2023.9.20)

# Steps to reproduce
1. Browse to https://kzar.co.uk/blog
2. Scroll to the bottom of the page.
3. Wait a few seconds.

# What happens
- The text goes blurry and is hard to read.

# What should happen
- The text stays sharp.

# Notes
- This started happening in the past few weeks.
- The problem doesn't happen when I use Firefox.
- I also see the problem on https://testpages.kzar.co.uk/

<Attached Screenshot.png>

Let’s break that down.

Environment

The environment section is where you mention2 any relevant details about how your browser and device are set up. Browser and Operating System version numbers are vital to include since often problems will occur with one version but not another. It’s also important to include a list of your enabled browser extensions, and if possible their versions too. Some browser extensions clash with one another, or clash with certain websites, so we need to know which browser extensions you are using. Often browser extensions are the root cause of the issue. Another important detail (though not shown above), is to list any advanced tracking protection and similar features that are enabled in your browser. For example, if you have Firefox’s “Enhanced Tracking Protection” feature enabled for the website (or you’ve disabled it), it’s well worth mentioning that. If you have an ad blocker and you’ve added custom filters or filter list subscriptions, list those too.

If you’re not sure about some of these details, that’s OK. Just try your best. Anything you can include here will save a lot of time, my first response is often to ask for these details.

Steps to reproduce

These are the specific steps someone needs to take to trigger the problem. If the bug is breaking a website, start with the full website address of the broken page and go from there. If the problem happens on multiple pages, just include one example here. Again, the goal is to help the development team reproduce the issue, not to include an exhaustive list of all the ways it can be triggered.

Carefully think through what all the steps are. One good tip is to try triggering the problem by following your steps in a fresh private/incognito tab. It’s important not to miss anything. Mention it if you need to log in to the website or change the website’s settings for the problem to occur. If the problem doesn’t happen immediately, roughly how long do you need to wait? If the problem doesn’t happen every time, mention that and which steps might need to be retried.

What happens

Clearly state what the problem is. “It’s broken” is not enough, but “The page starts to load, but then goes blank” is.

What should happen

Clearly state what should have happened instead. This one might seem silly, but often it really does help. The person reviewing this bug report might have never used the website before, so they might not understand how the website is supposed to work, or what you expected to happen. By explaining here you help them understand. Something as simple as “The website finishes loading and does not go blank.” is fine.

Notes

This is an optional section, in which you can include any other thoughts or notes that you think might be useful. If you have a suspicion about what the cause of the problem is, include a brief note. If you have noticed that the problem only started recently, or only happens on Wednesdays, or doesn’t happen in Chrome, or when you turn off your ad blocker - add a note. If the problem happens on many web pages, this is the time to mention it. Keep the notes short, quite often they aren’t as important as you might think, but it’s still worth sharing them.

Attachments

Sometimes it’s worth adding a file attachment to your bug report. Things to include:

  • A screenshot or screencast/video of the problem happening. Worth including if you can safely do so, but please be careful not to share your personal information - your bug report might be public and open to the world! Note that including a screenshot is a bonus, but it does not replace the written sections.
  • For more advanced bug reports, it might be necessary to attach some files which are needed to reproduce the problem. This is not usually necessary for most bug reports, but if for instance, you’re a developer reporting a complex bug it might be.

Anyway, just do your best and don’t worry if you don’t get it perfect first try! If the person investigating your bug asks some clarifying questions, try to answer those as best you can. Hopefully, you’ll be able to work together to get the issue resolved. Be kind with your words and be patient3, it goes a long way and is appreciated. Thanks for taking the time to write a good bug report!

Notes

  1. To investigate a bug, the first step is reproducing the issue. From there, the developer can start to figure out the cause, understand what’s going wrong, and work to fix the problem. Very occasionally, developers will work to fix an unreproducible bug. This will be in extreme circumstances, perhaps some serious issue is being reported by lots of people but the problem happens seemingly at random. Don’t count on this though. Hoping for a developer to fix an unreproducible bug is like playing the lottery as a retirement strategy. ↩︎

  2. Some environment details like the browser version might be automatically included by the bug reporting tool you’re using. Unfortunately, though, it’s usually not obvious which details will be sent automatically. When in doubt, include it yourself. ↩︎

  3. The volume of incoming bug reports can sometimes be overwhelming and hard to handle. We want to help you quickly, but sometimes that’s not possible. Forgive us if it takes a while. ↩︎