A bug report template is a fixed structure that tells whoever found a problem exactly what to write down so a developer can reproduce and fix it. Most reports fail because they skip the steps, the environment, or what the reporter actually expected. This post gives you a copy-paste bug report template, a GitHub markdown version, a detailed QA format, a filled-in example, and the rules for writing reports developers can act on without a follow-up.
If your team is still settling on a process, it helps to define how you document code and write up issues before you scale headcount. Treat the template as part of that process, not a one-off. Teams that already maintain repeatable process documentation tend to ship faster because nobody guesses at the format.
What makes a good bug report
A good report removes ambiguity. The developer reading it should know what broke, where, and how to see it themselves. Vague reports like "the app is broken" cost a round trip of questions before any work starts. The fields below carry that information.
| Field | What it captures | Required? |
|---|---|---|
| Title / ID | One-line summary with the affected feature | Yes |
| Environment | OS, browser, device, app version, build | Yes |
| Steps to reproduce | Numbered actions that trigger the bug | Yes |
| Expected result | What should have happened | Yes |
| Actual result | What happened instead | Yes |
| Severity | Impact: critical, major, minor, trivial | Yes |
| Priority | How soon it needs a fix | Recommended |
| Screenshots / logs | Visual proof, console output, stack traces | Recommended |
| Source URL / location | Page or screen where it occurred | Recommended |
| Reporter / date | Who filed it and when | Optional |
Two fields do most of the work. Steps to reproduce decide whether a developer can see the bug at all. Expected vs actual turns a complaint into a defect with a clear definition of done. Get those two right and the rest is context.
Severity vs priority
People mix these up. Severity measures how badly the bug hurts the product: a crash on checkout is critical, a misaligned icon is trivial. Priority measures how soon you fix it, which depends on release plans and customer impact. A low-severity typo on the pricing page can be high priority the week before a launch.
Bug report template (general, copy-paste)
This is the baseline. It works in any tracker, a shared doc, or an email. Paste it, fill each line, delete what does not apply.
Title: [Feature] Short description of the problem
Environment:
- OS / version:
- Browser / version:
- Device:
- App version / build:
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Severity: Critical / Major / Minor / Trivial
Priority: High / Medium / Low
Attachments: (screenshot, screen recording, console log)
Reported by: Date:
Keep the title scannable. Lead with the affected area in brackets so the tracker stays sortable, for example [Checkout] Promo code field rejects valid codes. That single habit makes a backlog searchable months later.
GitHub issue bug report template (markdown)
GitHub reads an issue template from .github/ISSUE_TEMPLATE/. Save the version below as bug_report.md and contributors get the structure prefilled every time they open a bug. This is the standard GitHub bug report template format with front matter.
---
name: Bug report
about: Report a defect so we can reproduce and fix it
title: "[Bug] "
labels: bug
assignees: ''
---
**Describe the bug**
A clear, concise description of what the bug is.
**Steps to reproduce**
1. Go to '...'
2. Click on '...'
3. Scroll to '...'
4. See error
**Expected behavior**
What you expected to happen.
**Actual behavior**
What actually happened.
**Screenshots / logs**
Attach visual proof or paste console output.
**Environment**
- OS: [e.g. macOS 15.2]
- Browser: [e.g. Chrome 142]
- App version: [e.g. 3.4.1]
**Additional context**
Anything else: frequency, recent changes, workaround.
The front matter (the block between the --- lines) controls the title prefix, auto-applied labels, and default assignee. Adjust those to match your workflow. Once committed, the template appears in the "New issue" picker for everyone in the repo.
Detailed QA bug report template
QA teams need more rigor than a general report. This format adds traceability fields that help during triage and regression testing. Use it when reports feed a formal test cycle or an audit trail.
Bug ID: BUG-0142
Title: [Login] Session expires after 30 seconds on mobile Safari
Reported by: J. Okafor
Date reported: 2026-06-22
Module / feature: Authentication
Build / version: 4.2.0-rc1
Environment:
- Device: iPhone 14, iOS 18.4
- Browser: Safari
- Network: Wi-Fi
- Account / role: Standard user
Preconditions: User has a valid account and is logged out
Steps to reproduce:
1. Open the login page on mobile Safari
2. Enter valid credentials and tap Sign in
3. Wait 30 seconds without interacting
4. Tap any navigation link
Expected result: Session stays active for the configured 60-minute window
Actual result: User is logged out and redirected to the login page
Severity: Major
Priority: High
Reproducibility: 5/5 (always)
Attachments: screen-recording.mov, network-har.json
Notes: Started after the 4.2.0-rc1 token refresh change
Two fields here earn their place. Reproducibility (how often the bug appears across attempts) tells the developer whether they are chasing a race condition or a guaranteed failure. Notes pointing at a recent change gives them a starting hypothesis, which often saves an hour of bisecting.
Filled-in bug report example
Here is the general template completed for a real-feeling defect, so you can see the level of detail that gets a fast fix.
Title: [Cart] Quantity stepper lets users order more than stock allows
Environment:
- OS / version: Windows 11 24H2
- Browser / version: Chrome 142.0.6
- Device: Desktop, 1920x1080
- App version / build: store-web 2.9.3
Steps to reproduce:
1. Open a product page for an item with 3 units in stock
2. Add the item to the cart
3. In the cart, click the quantity "+" stepper 6 times
4. Proceed to checkout
Expected result:
The stepper stops at 3 and shows "Only 3 left in stock"
Actual result:
Quantity reaches 9, checkout accepts the order, and the
confirmation email shows 9 units
Severity: Major
Priority: High
Attachments: cart-overflow.png, console-error.txt
Reported by: M. Reyes Date: 2026-06-23
Notice what this report does. The title names the feature and the failure in one line. The steps use a concrete stock number so the developer reproduces the exact condition. Expected and actual sit side by side, and the attachments back the claim with proof. No follow-up question needed.
Tips for writing reproducible bug reports
The difference between a report that gets fixed and one that gets ignored is usually detail discipline. These habits raise your hit rate.
- Write the steps as if the reader has never seen the product. Number them. Include the data you used, not just the action.
- Separate expected from actual every time. Even when it feels obvious, stating both prevents a developer from "fixing" the wrong behavior.
- Capture the environment before you forget it. Browser, OS, and build version change between sessions and matter more than people think.
- Attach proof. A 10-second screen recording or an annotated screenshot beats a paragraph of description. Paste console errors and stack traces as text, not images, so they are searchable.
- One bug per report. Bundling three issues into one ticket guarantees at least one gets lost.
- Record reproducibility. "Happens every time" and "happened once" lead to completely different investigations.
A report that hits these notes survives triage and lands in a sprint instead of a "need more info" queue. According to the 2025 Stack Overflow Developer Survey, more than 80% of developers spend time each week dealing with technical debt and unclear requirements, and ambiguous bug reports feed directly into that drag.
Where to keep your bug reporting standard
A template only works if everyone uses the same one. The common failure is a format that lives in a Slack message someone pasted in 2024, or a wiki page nobody can find. The standard belongs somewhere searchable, versioned, and linked from your contributor docs.
This is where a docs site earns its keep. Tools like Docsio keep contributor and bug-reporting guidelines in a searchable docs site, so the template, the severity definitions, and the example sit next to your other process docs instead of scattered across chat threads. You can generate the structure from an existing wiki or repo with AI-assisted doc generation and edit it live, which means the standard stays current as your process changes.
Pairing your bug template with the related runbooks helps too. A clear incident response template covers what happens after a critical bug ships, a blameless post-mortem template captures the lessons, and an operational runbook template documents the recurring fixes. Together they form the response layer around the bug report itself.
Frequently asked questions
What should a bug report include?
A bug report should include a clear title naming the affected feature, the environment (OS, browser, device, build), numbered steps to reproduce, the expected result, the actual result, a severity rating, and supporting proof like screenshots or console logs. Steps and expected-versus-actual are the most important fields.
How do you write a good bug report?
Write a specific title, list numbered reproduction steps using the exact data you used, and state expected and actual results separately. Record the environment, rate severity and priority, attach a screenshot or recording, and limit each report to one bug. Detail and reproducibility decide whether it gets fixed quickly.
What is a bug report?
A bug report is a structured record of a software defect that gives developers enough information to reproduce, prioritize, and fix the problem. It documents what broke, where, the conditions involved, and what the correct behavior should be, turning a vague complaint into an actionable engineering task.
What is the difference between a bug and a defect?
In most teams the terms are used interchangeably. Strictly, a defect is any flaw in the software that causes it to behave incorrectly against its requirements, while a bug is the observable symptom a user or tester encounters. A bug report documents the symptom and traces it back to the underlying defect.
What is severity in a bug report?
Severity measures how badly a bug affects the product, independent of when you fix it. Common levels are critical (crash or data loss), major (a core feature broken), minor (a small functional issue), and trivial (cosmetic). Priority, by contrast, decides how soon the fix gets scheduled.