# How to Write a Bug Report Your Developer Can Fix

> Write one report per bug with a short title, the exact URL, numbered steps to reproduce, what you expected, what actually happened, your device and browser with version, the time it happened and a screenshot or short video. That lets the developer reproduce the problem straight away instead of hunting for it on your bill.

- URL: https://kleinerauftrag.de/en/scoping/how-to-write-a-bug-report/
- Language: en
- Updated: 2026-10-19
- Publisher: Kleiner Auftrag (OnlineBuilders LLC, https://onlinebuilders.biz)

Here's what a developer sees when your email says "the checkout is broken": a shop with forty pages, three payment methods, two currencies and no clue where to start. Before anyone can fix a problem they have to see it with their own eyes. Every minute spent guessing which page, which phone and which button you meant is a minute on your invoice.

Good bug reports fix that. Think of yours as the cheapest part of the repair.

## What goes into a bug report

Mozilla's bug writing guidelines for Bugzilla call the steps to reproduce the most important part of any report. Around them sit a clear summary, the expected result, the actual result, and version and platform details. Translated to a small business website, that becomes:

- **Title:** about ten words describing the problem, not the fix. Mozilla suggests staying under 60 characters.
- **URL:** the full address, not "on the product page".
- **Steps:** numbered, so a stranger could click through them.
- **Expected:** what should happen.
- **Actual:** what happens instead, including any error message word for word.
- **Environment:** device and operating system, plus browser and its version.
- **Frequency:** every time, sometimes, once.
- **When:** date and time, ideally to the minute.
- **Evidence:** screenshot or screen recording.

That's it. Adding when the problem started and whether anything changed just before saves the developer their first question.

## Bug report template you can copy

```text
Title: [What happens, where] e.g. "Basket empties after login on mobile"

URL: https://...

Steps to reproduce:
1.
2.
3.

Expected result:

Actual result:
(copy the error message exactly, or attach a screenshot)

Environment:
Device / OS:
Browser and version:
Logged in as: (role, never the password)

Frequency: always / sometimes (x out of 10) / once
When: YYYY-MM-DD, hh:mm (time zone)
Started when / what changed before:

Attachments: screenshot, video, console output
Impact: blocks sales / annoying / cosmetic
```

The impact line is the single most useful planning detail for the developer. "Blocks sales" means today. "Cosmetic" means next time they're in the code anyway. If you and your developer work in different time zones, the time zone next to the timestamp matters more than you'd think.

## Example: before and after

Here is a typical email: "Hi, checkout isn't working, customers are complaining, please look at it urgently." The search starts there. Which payment method? All customers or some? Since when?

The same problem, written up with the template:

- **Title:** Card payment fails on Android with "Something went wrong"
- **URL:** https://example-shop.co.uk/checkout/
- **Steps:** 1. Add any product to the basket. 2. Go to checkout as a guest. 3. Choose card payment. 4. Tap "Pay now".
- **Expected:** the card form opens and payment completes.
- **Actual:** message "Something went wrong", no order is created.
- **Environment:** Samsung Galaxy S23, Android 15, Chrome. Works fine on a laptop with Firefox.
- **Frequency:** five out of five attempts on the phone.
- **When:** 14 October, 09:42 BST, video attached.

With this version the developer knows to test on Android in Chrome and can search the logs around 09:42. An open-ended hunt has become a targeted check.

**What the developer learns from the report**

| | "Checkout is broken" | Report using the template |
|---|---|---|
| Affected page | no | yes |
| Steps to reproduce | no | yes |
| Device and browser | no | yes |
| Timestamp for log search | no | yes |
| How urgent it is | partly | yes |
| Effort can be estimated upfront | no | partly |

## How to find browser version, record your screen and open the console

The technical fields put people off. They take two minutes.

**Browser version.** In Chrome it's under Settings, "About Chrome". Edge has "About Microsoft Edge" in the same place. Firefox shows it under Help, "About Firefox", and Safari on a Mac under Safari, "About Safari". On an iPhone the iOS version from Settings is enough, because Safari is tied to it.

**Screen recording.** A short video often says more than any description. On a Mac, Shift + Cmd + 5 opens the screen recording controls. On Windows 11 the Snipping Tool can record video. iPhones and Android phones have screen recording in Control Center or the quick settings panel. Twenty seconds is plenty.

**Console.** For bugs on web pages the browser console is gold. Chrome and Edge open it with F12 or Ctrl + Shift + J, on a Mac with Cmd + Option + J. Red lines are errors. Take a screenshot of them, even if they mean nothing to you.

Before you send the report, try the same steps in a private window. If it works there, the cause is probably cached files, cookies or a browser extension. That belongs in the report too.

## How urgent is it, honestly?

Nearly every bug feels urgent in the moment. For planning, separate two questions: how bad is it, and how fast must it go? Testers call these severity and priority. Crashed checkout? Severe and urgent. Wrong date in the footer? Minor, though it can still become urgent before an audit.

Three levels are enough for small jobs, and each report should state one:

| Level | Meaning | Expected response |
|---|---|---|
| Blocking | Sales, enquiries or logins are failing | Same day, possibly at a rush rate |
| Annoying | Works, but clumsy or partly wrong | Within a few working days |
| Cosmetic | Layout, typos, spacing | Next scheduled session |

Flag everything as blocking and you lose credibility fast. Work outside normal planning can also come with a surcharge, which is often written into a freelancer's terms. Honest triage saves money. What a small fix typically costs is covered in our guide to the [cost to update a website](https://kleinerauftrag.de/en/costs/website-update-cost/).

## One bug per report

Mozilla's guidelines say it plainly: one bug per report. The same applies to small jobs. Five bugs in one email usually means four get fixed and one gets forgotten, and later nobody knows which.

Separate reports have another upside. Each can be estimated on its own, so you can decide that the checkout failure gets fixed now and the wonky footer waits for the next maintenance slot.

Watch what you attach. Screenshots from the admin area sometimes show customer data or credentials. Blurring them takes ten seconds. If the developer needs a login to reproduce the bug, don't paste it into the report. Use one of the safer ways to [share passwords with a developer](https://kleinerauftrag.de/en/delivery/share-passwords-with-developer/).

## When a bug report turns into a job

Your bug report describes what's broken. It doesn't yet say what should be true after the fix. For simple cases that's obvious: checkout should work again. For anything beyond that, add one sentence describing how you'll check the fix. Our [acceptance criteria examples](https://kleinerauftrag.de/en/scoping/acceptance-criteria-examples/) show how to phrase it.

If reports pile up, the same areas keep breaking and every fix seems to cause a new problem, you're looking at a structural issue rather than a string of bad luck. One steady partner for [development and operations](https://onlinebuilders.biz/solutions/software-development) often costs less than the next round of one-off jobs.

For the bug in front of you right now: copy the template, record a 20-second video and send both together. If you want to go deeper, the [Bugzilla bug writing guidelines](https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html) also cover crashes and performance problems.

## FAQ

### What is the difference between severity and priority?

Severity describes how badly the bug affects the system. Priority says how soon it should be fixed. A typo on the homepage has low severity, but it can have high priority the day before a big campaign goes live.

### Should I guess what is causing the bug?

You can, as long as you keep it separate from what you observed and label it as a guess. Something like "started after Tuesday's plugin update" is genuinely useful. "Probably the server" with no reason tends to send people down the wrong path.

### What if the bug only happens sometimes?

Say how often, for example three out of ten attempts, and note the time, device and what you did just before each time it happens. With timestamps, the developer can look for matching entries in the server logs.

### Can I put several bugs in one email?

Better not. One report per bug can be estimated, fixed and ticked off on its own. If you do send a combined email, number the bugs and give each its own steps.

Photo: Lklundin, CC BY-SA 4.0 (https://commons.wikimedia.org/wiki/File:Computer_Screen_with_software_error_at_Gate_11_(SCL).jpg)