How to Write a Bug Report Developers Can Fix (With a Template)

A bug report developers can fix has a specific title, numbered steps to reproduce, the expected result, the actual result, the environment (build, browser or device, account and role), how often it happens, and evidence such as a screenshot, recording or log. One bug per report. If a developer can reproduce it on the first try, the report did its job.

If you would rather have testing and bug reporting done for you, see how RAITHub would test this below. Reports like these usually come out of exploratory testing sessions.

What makes a bug report fixable?

Reproducibility. A developer who cannot make the bug happen cannot confirm a fix, so a report without reliable steps tends to sit in the backlog marked "cannot reproduce".

Mozilla's long-standing bug writing guidelines call steps to reproduce "the most important part of any bug report", ask for a summary that explains the problem rather than a suggested solution, and say to open a separate report for each issue. Those three rules cover most of what goes wrong in bug trackers.

What is a good bug report template?

Copy this into your tracker's description field or save it as a template. Replace everything in square brackets.

TITLE
[Where] [what goes wrong] [under which condition]
e.g. Checkout: order total ignores discount code when currency is EUR

ENVIRONMENT
Build / version: [release number or commit]
URL or screen:   [exact URL or app screen]
Browser / device: [e.g. Chrome 141 on Windows 11, or iPhone 15, iOS 26]
Account / role:  [test account and role, never a real password]
Test data:       [order id, record id, file used]

STEPS TO REPRODUCE
1. [First action, with exact values]
2. [Next action]
3. [Action that shows the problem]

EXPECTED RESULT
[What should happen, and where that is defined if known]

ACTUAL RESULT
[What happened instead, with exact messages or values]

FREQUENCY
[Every time / X of Y attempts / once]

SEVERITY
[Blocker / Critical / Major / Minor / Trivial]

EVIDENCE
[Screenshot, screen recording, console errors, network request id, log excerpt]

NOTES
[Workaround, first build where it appeared, related tickets]

What does each field need?

Field	Weak	Strong
Title	Checkout broken	Checkout: order total ignores discount code when currency is EUR
Environment	Chrome	Build 2.14.0, Chrome 141 on Windows 11, staging, buyer role
Steps	Add stuff to cart and pay	Numbered steps with the product, quantity, code and currency used
Expected	Should work	Total is 90.00 EUR after the 10% code SAVE10
Actual	Wrong price	Total shows 100.00 EUR; code shows as applied; the receipt email says 100.00 EUR
Frequency	Sometimes	5 of 5 attempts in EUR; 0 of 5 in USD
Evidence	None	Screen recording, the order id, and the failing network request

The strong column already narrows the cause: it only happens in EUR. A frequency line comparing conditions is often the most useful sentence in a report.

How do you write steps to reproduce?

• Start from a known state. "Logged in as the test buyer, cart empty" beats "go to the cart".
• One action per step, with exact values: which product, how many, which code.
• Reproduce it yourself before filing, following only your written steps. If you cannot, say so and give the frequency.
• Trim the steps. Remove anything that does not affect the result. Mozilla's guidance asks for steps that are minimised and easy to follow.
• Do not guess the cause in the steps. Put theories in Notes, clearly marked.

How do you set severity and priority?

Severity is how bad the impact is. Priority is how soon it should be fixed. They often match, but not always: a typo on the home page is low severity and may be high priority before a launch.

Severity	Meaning	Example
Blocker	Stops a core journey or a release, with no workaround	Nobody can sign in
Critical	Data loss, money wrong, security or privacy exposure	User B can see user A's invoices
Major	An important feature fails, but a workaround exists	Export fails; data can still be copied by hand
Minor	Works, but wrong in a way users notice	Date shown in the wrong format
Trivial	Cosmetic	Misaligned icon

Agree these definitions once, with examples from your own product, so severity is not argued ticket by ticket. Leave priority to whoever owns the backlog.

What evidence should you attach?

• A screen recording for anything involving steps or timing. Thirty seconds of video beats three paragraphs.
• A screenshot with the problem area marked.
• Console errors from the browser's developer tools, copied as text.
• The failing network request: URL, status code and response body, with any tokens removed.
• IDs: order, user, request or error-tracking event IDs let a developer find the server logs.
• Never real passwords or customer personal data. Use test accounts and redact screenshots.

How do you make every report follow the template?

Put the template in the tracker so nobody starts from a blank box. On GitHub, issue forms do this: a YAML file in .github/ISSUE_TEMPLATE turns the template into required fields, as described in GitHub's issue template docs. A minimal form:

name: Bug report
description: Something does not work as expected
labels: ["bug"]
body:
  - type: input
    id: environment
    attributes:
      label: Environment
      description: Build, browser or device, account role
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      placeholder: "1. ...\n2. ...\n3. ..."
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected result
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual result
    validations:
      required: true
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options: [Blocker, Critical, Major, Minor, Trivial]
    validations:
      required: true

Jira, Linear and most other trackers support description templates or required fields in the same spirit.

What are the common bug report mistakes?

• Several bugs in one ticket. One gets fixed, the ticket closes, the others are lost.
• A solution instead of a problem. "Add a retry button" hides what actually failed.
• Missing the build. The bug may already be fixed, or may be new in this release.
• "It doesn't work". Always say what happened instead.
• Duplicates. Search the tracker first and add evidence to the existing ticket.

Once a bug is fixed, protect against its return with a test that fails if it comes back; regression testing after every deploy explains how to wire that into CI.

Buy, build or hire?

Option	What you get	Choose this when	Watch out for
A tool or SaaS testing platform	Bug trackers, screen recorders and capture tools that attach logs automatically	Your team files bugs but they lack evidence	A tool captures data; it does not write clear steps
Freelancers or crowdtesting	Outside testers filing reports, often paid per test cycle or per bug	You want many fresh eyes for a short period	Paying per bug can reward volume over quality; set a report standard first
An in-house QA hire	A tester who owns the bug process and triage	Bug volume is steady and the product is large	One person's reporting style becomes the standard, good or bad
A managed QAaaS team	Testing plus reproducible reports filed into your tracker	You want testing done and reports developers can act on	Ask for sample reports before you sign

Why RAITHub for testing and bug reporting?

• Reports written for developers by people who develop. RAITHub engineers build and fix production software, so reports include the evidence they would want themselves.
• Bugs that stay fixed. Within RAITHub's QA as a service, a confirmed bug can become an automated regression test in your CI.
• Everything in your tracker. Reports are filed where your team already works, and they stay yours.

When you don't need us

• Your team already files clear reports. Add the template and the issue form, and you are done.
• You have a handful of bugs a month. A good template matters more than a QA service at that volume.

How RAITHub would test this

• Scope: agree severity definitions with you; set up a bug template or issue form in your tracker; run manual and exploratory testing on your key journeys; file reproducible reports with evidence; retest fixes and close the loop.
• How you buy it: a fixed-price one-off audit, a monthly QA plan, or a dedicated QA team that RAITHub manages and bills monthly. No staff augmentation.
• Timeline: fixed in the written quote.
• What you receive: bug reports in your tracker, a summary report, and a list of fixed bugs worth turning into automated tests, under an NDA as standard. See the manual testing service.
• Next step: a free 15-minute audit call, then a fixed written quote.

To get testing with reports your developers can act on, choose QA / Reliability on the contact form.

Last reviewed: 7 October 2026.

Frequently asked questions

What should a bug report include?

A specific title, the environment, numbered steps to reproduce, the expected result, the actual result, how often it happens, severity and evidence such as a screenshot or recording. One bug per report.

What is the difference between severity and priority?

Severity measures the impact of the bug. Priority decides how soon it gets fixed. A cosmetic issue on a launch page can be low severity and high priority.

What if I cannot reproduce the bug every time?

File it anyway, say how often it happens (for example 2 of 10 attempts), and attach everything you have: time, account, request IDs and logs. Developers can often find intermittent bugs from server logs.

Should a bug report suggest a fix?

Describe the problem first. If you have a theory about the cause or fix, add it under Notes and label it as a theory, so it does not get mistaken for the requirement.

How long should a bug report be?

As short as possible while still letting a developer reproduce it on the first try. Most good reports fit on one screen, plus attachments.

Does RAITHub write bug reports into our own tracker?

Yes. RAITHub files reports into the tracker your team already uses, following severity definitions agreed with you.