Why Format Is Overlooked More Than Content
A bug report format is 10 fixed fields arranged in four groups: identity → environment → symptom → evidence. Fix the order and a developer knows exactly where to look, without asking you a second time. Below are the full field list, writing rules with good and bad examples for each field, and the 7 format mistakes that quietly kill otherwise decent reports.
The same information written in a different format costs twice as much to process. Inconsistent formats cause three problems:
The value of a format isn't that it looks tidy. It's that the same field always sits in the same place.
The Standard Bug Report Format: 10 Fields
| # | Field | Purpose | Required? | How to write it |
|---|---|---|---|---|
| 1 | Title | Lets a developer decide whether to open the ticket | Required | Component + action + unexpected result + condition (see bug title examples) |
| 2 | ID | Lets everyone reference the same record | Required (auto-generated) | BUG-0042, never "the one from earlier" |
| 3 | Severity / Priority | Basis for scheduling | Recommended | Severity measures damage, priority measures business urgency — keep them separate |
| 4 | Environment | Determines whether the report can be reproduced | Required | URL, browser version, OS, device, resolution, account |
| 5 | Preconditions | The starting state for reproduction | Recommended | "Signed in as an enterprise account with 2 items already in the cart" |
| 6 | Steps to Reproduce | Walks someone to the same screen | Required | Numbered, one action per step (see how to write steps to reproduce) |
| 7 | Expected Result | The basis for deciding "is this a defect?" | Required | State what should happen, never "it doesn't work properly" |
| 8 | Actual Result | Factual description | Required | Symptom + numbers + the exact error text, with no speculation |
| 9 | Evidence | Saves the developer from re-running everything | Strongly recommended | Annotated screenshots, screen recording, console logs, failed requests |
| 10 | Notes | Extra context | Optional | Frequency, workarounds, related tickets |
How to Write Each Field
Identity: Title, ID, Severity and Priority
- Title: one line covering where, what you did, what went wrong and under what condition. For 40 side-by-side good vs bad examples, see bug title examples.
- ID: let the system generate it. Manual numbering always produces duplicates.
- Severity vs priority: the pair most often merged into one field.
| Field | Question it answers | Who decides | Example |
|---|---|---|---|
| Severity | How much damage does the defect itself cause? | Tester / reporter | Data loss = critical; a typo = minor |
| Priority | When will we fix it? | Product / engineering lead | A typo on the hero section on launch week = high priority |
Environment: Environment and Preconditions
The environment field must cover all six items: URL, browser and version, operating system, device, resolution/viewport, and account type. Writing "Chrome" alone is the same as writing nothing — behaviour differences between browser versions are routine on the web.
The precondition people forget most often isn't login state but data state: "2 items already in the cart", "account is on day 3 of the trial", "this order already had one refund issued". That's what actually blocks reproduction.
Symptom: Steps to Reproduce, Expected Result, Actual Result
- Steps to reproduce: numbered, one action per step, real data. The full method is in how to write steps to reproduce.
- Expected result: state what should happen and cite the source where you can (a requirements item, an acceptance criterion ID, or plain common sense). Writing "it should work properly" pushes the judgement back onto the developer.
- Actual result: only facts, with numbers and the exact error text. No speculation — move guesses like "probably a caching issue" into Notes and mark them as "suspected".
Evidence: Screenshots / Recordings / Logs, and Notes
- Screenshots must be annotated: circle the problem area and add arrows or text so nobody has to hunt across a full-screen capture.
- Screen recordings should run 10–30 seconds and keep only the relevant moment — a five-minute recording usually goes unwatched.
- Logs should include only the useful parts: error-level console output, failed network requests (HTTP ≥ 400), and the request/response bodies of the key endpoint.
- Notes should carry two things: frequency (always / intermittent, with a probability) and any workaround.
Format Differences Across Three Channels
| Channel | How fields appear | The trap |
|---|---|---|
| Issue tracker (Jira / Linear / GitHub Issues) | Custom fields plus a description template | Environment info written at the end of the description and buried in long text — it belongs in custom fields |
| Email or chat (sent to a client or external collaborator) | Plain text blocks | No TL;DR, and attachments named at random so the reader searches through a dozen files |
| Spreadsheet (Excel / Google Sheets / Feishu Bitable) | One row per bug, columns = fields | Column order doesn't match the 10 fields, so filtering and sorting fall apart |
The channel changes, the fields don't. Missing information isn't forgiven just because it was sent as an email.
7 Format Mistakes That Ruin a Report
screenshot-1.png, unmatched by the reporter themselves three days later.Format Checklist
Confirm each line before you submit:
- All 10 fields present, in the same order as last time?
- All six environment items (URL / browser / OS / device / resolution / account) filled in?
- Expected and actual results written separately?
- Steps numbered, with one action per step?
- Screenshots annotated and recordings under 30 seconds?
- No unverified speculation anywhere in the actual result?
- Frequency stated clearly (always / intermittent + probability)?
FAQ
Is there a "standard" bug report format?
No enforced industry standard exists, but there is a de facto consensus: title, environment, steps to reproduce, expected result, actual result and evidence appear in virtually every framework (IEEE 829, ISTQB, and most commercial defect templates). The 10 fields here add the identity and notes fields to that core.
Can we change the field order?
Yes, as long as it stays consistent and stable within the team. The point of a fixed order is muscle memory — developers know where to scan. Changing the order frequently hurts more than picking a suboptimal one.
What's the real difference between severity and priority?
Severity describes the objective damage of the defect (judged by testing); priority describes how urgently it must be fixed (judged by product). They can diverge: a typo in the hero section has low severity, but if launch is in three days its priority is high.
Do simple bugs really need all 10 fields?
No. A simple bug can get away with title, environment and actual result — but never drop environment, the number one source of "cannot reproduce". Fields are optional; positions are not.
What's the difference between a "format" and a "template"?
A format is the field specification: which fields exist, in what order, and how each one is written. A template is a skeleton file you copy and fill in. They work together — define the fields by format, then ship them as a template. If you want the fill-in-the-blank skeleton, see bug report template (with Word and Markdown versions).
Format Can Be Automated; the Judgement Is Yours
Let's be precise about the boundary: BugCapturer won't decide what counts as a defect, and it won't write your title — that takes your understanding of what you saw. But the parts people forget and the parts that eat time can fill themselves in:
- Automatic technical context: URL, browser, operating system, screen resolution and viewport size are written into the environment field for you, no copying by hand.
- Diagnostic data: error-level console logs and failed network requests (HTTP ≥ 400) are collected, with sensitive parameters (tokens, passwords, API keys) redacted automatically.
- Annotated screenshots: drag to select the area, then add arrows, boxes and text — "where it's wrong" is pinned into the image.
- Screen recording: record the current tab and trim the clip, so developers get a short video they can verify against.
- Share or sync: generate a share link external collaborators can open without registering, or push the report into Feishu Bitable or a generic webhook.
You keep the judgement. The tool handles the rest.
Further reading
- Bug report template: the full field set with a copy-paste skeleton
- Bug title examples: 40 good vs bad titles compared
- How to write steps to reproduce: 5 complete examples
- How to report bugs effectively
- Website QA checklist