Templates / Bug report
A bug report template that gets bugs fixed
A bug gets fixed when the person fixing it can see it for themselves. Every field below exists to get them there: what happened, how to make it happen again, and where it happened. Copy the template into your tracker, your wiki or your support macros.
The template
## What happened
<!-- One or two sentences, in the words of whoever hit it. -->
## What I expected
## Steps to reproduce
1.
2.
3.
## Where
- Page / URL:
- Browser and version:
- OS and device:
- Screen size:
- Signed in as:
## Screenshot or recording
<!-- Mark the part that's wrong. -->
## Console errors
```
<!-- Paste anything red from the browser console. -->
```
## How often
<!-- Every time, sometimes, once? -->What each part is for
| Part | Why it's there | Good | Not enough |
|---|---|---|---|
| What happened | The symptom, so the reader knows what to look for | Tapping Pay does nothing: no spinner, no error, the button stays blue | Checkout is broken |
| What I expected | Separates a bug from a misunderstanding | To go to the confirmation page | To work |
| Steps to reproduce | The fastest way to see it is to do it | Add any item, go to checkout, pick card, tap Pay | Just try to pay |
| Where | Many bugs only happen in one browser or at one size | Safari 18, macOS, 1440 × 900 | On my laptop |
| Screenshot or recording | Shows what words miss, like the wrong button | The Pay button circled | A screenshot of the whole desktop |
| Console errors | Often names the cause outright | TypeError: Cannot read properties of undefined (reading 'confirmCardPayment') | Nothing in the console (when there was) |
| How often | Tells an intermittent bug from a constant one | Every time, on two cards | Randomly |
A good report and a bad one
The bad one is what most teams get from users:
Subject: checkout broken!!
Can't pay. Please fix asap.The good one, for the same bug:
## What happened
Tapping Pay does nothing. No spinner, no error; the button stays as it was.
## What I expected
To land on the order confirmation page.
## Steps to reproduce
1. Add any item to the cart
2. Go to checkout and choose "Card"
3. Tap Pay
## Where
- Page / URL: https://shop.acme.example/checkout
- Browser and version: Safari 18.1
- OS and device: macOS, MacBook Air
- Screen size: 1440 × 900
- Signed in as: maya@example.com
## Console errors
TypeError: Cannot read properties of undefined (reading 'confirmCardPayment')
## How often
Every time, tried twice with two different cards.Getting reports like that from users
Your team will fill in a template. Your users mostly won't: they don't know what a console is, and they shouldn't have to. That is what Brainbox is for. Users click a button in your app, mark what's wrong and say what happened, and the widget fills in the rest of this template itself: the page, browser, screen size, who they are, the element they marked and the console errors. It then files it as a GitHub issue or an Azure DevOps work item.
For GitHub, there is also an issue form version of this template, with required fields and dropdowns.
Try it before you install it
The button in the corner of this page is the real widget. Report something on this page and it lands in our inbox, the way your users’ reports will land in yours.
Get started