How to write a bug report that gets fixed
A developer reading your report needs to answer three questions fast: can I see it happen, do I know where to look, and how bad is it? Every section of the template exists to answer one of those.
1. A title that names the place and the problem
“Checkout: total ignores SPRING10 discount” is searchable and triageable. “Checkout broken!!” isn’t. Lead with the area, then describe the behaviour, not your guess at the cause.
2. Steps someone else can follow
Start from a clean state, write one action per line and include the exact input. If it only happens sometimes, say how often (“3 of 5 attempts”). Reproducible steps are the single biggest factor in whether a bug gets fixed quickly.
3. Expected vs actual, side by side
Spell out what you expected even when it seems obvious; the reader may not know the rule. Copy error messages exactly, as text, so they can be searched in logs and code.
4. Evidence: an annotated screenshot
A screenshot with a box around the problem and numbered steps removes most back-and-forth. Annotate it here: box the wrong value, number the steps, and blur customer data. For interaction bugs, add a short screen recording and the browser console output.
5. Environment and severity
Browser and version, OS, device, screen size, app version or commit, and the account type or feature flags involved. Then rate severity by impact using the scale below.
Severity scale
| Severity | Meaning | Example |
|---|---|---|
| Blocker | Stops work or release; no workaround. | Checkout fails for every card. |
| Critical | Core feature broken or data loss/security risk. | Saved drafts are deleted on logout. |
| Major | Important function wrong; workaround exists. | Discount not applied to total. |
| Minor | Limited impact or cosmetic but noticeable. | Pay button overflows its card at 1280 px. |
| Trivial | Polish; nobody is blocked. | Tooltip text has a double space. |
Severity is about impact; priority (when to fix it) is the team’s call. The ISTQB glossary defines the two separately for the same reason.
Common mistakes
- Several bugs in one ticket. They get fixed and closed at different times, so split them.
- Screenshots of the whole desktop with no marks. Crop and point.
- “Doesn’t work” with no actual result. What did you see?
- Secrets in screenshots and logs. Redact tokens, passwords and personal data before posting.