QUICK ANSWER
What should a bug report template include?
A bug report template should describe one observed defect with expected and actual behavior, ordered reproduction steps, the exact environment and version, sanitized evidence, measured frequency and impact, a severity rationale, a human triage decision, and a retest tied to the target fix version. Keep test strategy, change approval, security incidents, and release decisions in their own records.
A useful bug report keeps one observed defect attached to the exact expected behavior, actual behavior, reproduction steps, environment, sanitized evidence, severity input, human triage decision, and version-bound retest. It helps another person reproduce what happened without guessing which version, fixture, or state the reporter used.
This downloadable pack includes an editable Markdown worksheet, a valid JSON starter, a closed JSON Schema, a fictional completed example, and a dependency-free validator with deterministic tests. It is not a test strategy, change request, security incident report, implementation approval, release authorization, or promise that every defect will be found or fixed.
Record one observed defect from reproduction to retest
Start with the observation rather than a proposed solution. Preserve the exact steps and environment, sanitize evidence, let a human decide triage, and close only against the version that was actually retested.
Separate one observation from duplicates and proposed work
Search the tracker before opening a new record, then give one observed defect a stable ID, revision, concise title, expected behavior, actual behavior, impact, and frequency. Keep solution design, implementation authorization, and broader test strategy outside this record so triage can evaluate the evidence before choosing work.
Sources: [bug-report-pack], [github-issue-forms], [mdn-file-browser-bugs]
Make the reproduction and environment exact
Write ordered actions from a known synthetic fixture or minimal case. Record application version, release ID, target, operating system, browser or runtime, viewport, locale, feature flags, and attempt counts. Use reserved .test hosts for fictional examples instead of real customer or internal addresses.
Sources: [bug-report-pack], [mdn-file-browser-bugs], [rfc-2606]
Attach sanitized evidence and explain severity
Give each screenshot, log, trace, or minimal reproduction an ID, capture time, safe reference, hash, redaction confirmation, and note. Remove session tokens, passwords, API keys, personal data, private URLs, and unrelated records. Record severity with impact, scope, frequency, data-loss observation, and the private escalation boundary for security or privacy concerns.
Sources: [bug-report-pack], [owasp-logging]
Validate the record before human triage
Use a closed schema and validator to reject missing fields, unknown keys, unsafe URLs, unordered steps, broken evidence references, impossible counts, and incompatible states. Structural validity makes the record reviewable, but it does not choose priority, assign an engineer, approve a change, or prove the observation is authentic.
Sources: [bug-report-pack], [json-schema-2020-12]
Retest the same steps against the named fix version
After an accepted defect names a target version, repeat the recorded reproduction steps and capture new evidence. Close only when the retest passes on that target version and its evidence IDs resolve to the same record. Preserve the original failed observation, workaround, and triage reason after closure.
Sources: [bug-report-pack], [github-issue-forms], [mdn-file-browser-bugs]
The single-defect evidence boundary
Use this template to make one observed software defect reproducible and reviewable. Link adjacent records where needed, but do not turn the bug report into a universal delivery or assurance document.
Included
- Stable report ID, revision, reporter role, observation time, concise title, component, and lifecycle status
- Expected behavior, actual behavior, measured impact, frequency, affected version, last known good version, and workaround
- Preconditions, ordered steps, minimal case, reproduced count, attempt count, exact environment, release, fixture, and flags
- Sanitized evidence references with type, timestamp, SHA-256, redaction confirmation, and a short factual note
- Severity rationale and scope, human triage state, role owner, decision time, reason, duplicate link, or target version
- Version-bound retest state, repeated-step confirmation, observed result, and resolving evidence IDs
Not included
- A test strategy, test plan, regression matrix, coverage claim, acceptance plan, or proof that every defect was found
- A change request, implementation specification, effort estimate, schedule, commercial approval, or authorization to start work
- A public security vulnerability, privacy incident, credential leak, personal-data record, or replacement for a private incident process
- A root-cause conclusion, fix design, code review, deployment action, release approval, rollback decision, or operational runbook
- Proof that evidence is authentic, severity is final, a duplicate search is complete, a fix works everywhere, or production matches the test environment
- A guarantee of response time, ownership, priority, remediation, reliability, security, privacy, compliance, release safety, or business outcome
DOWNLOADABLE RESOURCE
Download the bug report template pack
Start with the Markdown worksheet for review or the valid JSON starter for automation. Compare the completed fictional example, inspect the closed JSON Schema, then run the included validator and tests without installing dependencies.
Single-defect bug report template pack
A fictional, version-bound bug-report record connecting one observed form-state defect and its expected and actual behavior to reproduction, environment, sanitized evidence, severity input, human triage, and a passed retest.
Format: Markdown, JSON, JSON Schema, and dependency-free Node.js validator/tests in one ZIP
Locally reproduced August 1, 2026. SHA-256: 29fe254dc261c800dd5e91b9d301263f289e10b4a87d46c42ef4f68755bac402
Included
- Editable Markdown worksheet and a valid fictional JSON starter
- Completed fictional JSON example for one observed defect, accepted triage, and passed version-bound retest
- Draft 2020-12 closed JSON Schema with exact root and nested record shapes
- Dependency-free Node.js validator covering references, URLs, counts, timestamps, versions, boundaries, and state transitions
- Thirty-four deterministic contract tests for valid and rejected record states
- README, package commands, fixed source timestamps, exact eight-file allowlist, and reproducible ZIP bytes
Verification boundary
Rebuilt twice with fixed source timestamps and stripped ZIP metadata. Verified the exact eight-file allowlist, source-to-public-to-archive byte parity, clean extraction, 34 validator tests, starter and example validation, closed schema, exact object keys, semantic versions, UTC timestamps, ordered steps, attempt counts, reserved fictional URLs, evidence IDs and hashes, redaction confirmations, chronology, severity escalation boundary, triage transitions, target version, version-bound retest, no secret-like values, and all-false ownership boundaries.
Three bug-report patterns
The evidence record stays stable while the observed behavior changes. Each pattern owns one defect and names what is known, what is measured, and what still requires human triage.
Deterministic form validation state defect
Use when: A control remains disabled or invalid after the user corrects the field that originally caused validation to fail.
Record the valid expectation, stale actual state, synthetic fixture, exact input order, affected version, three of three attempts, and a sanitized state screenshot. Let a maintainer accept the defect, then repeat those steps against the named fix version before closure.
Structure
- One stable report ID connects observation, environment, evidence, triage, and retest
- Ordered steps isolate the invalid-to-valid transition instead of saying the form is broken
- The passed retest names the target version and points to evidence captured after execution
Watch for: The report documents an observed state transition. It does not choose the implementation, approve a change, establish regression coverage, or authorize release.
Sources: [bug-report-pack], [github-issue-forms], [json-schema-2020-12]
Environment-specific browser rendering issue
Use when: A layout or interaction fails only in a particular browser, operating system, viewport, locale, flag set, or release.
Reduce the behavior to a reserved minimal case, compare at least one unaffected environment, and record the exact browser, operating system, viewport, locale, flag, and release. Attach sanitized screenshots and state only the environments actually observed.
Structure
- Minimal .test case removes unrelated application and customer state from the observation
- Exact affected and comparison environments replace vague labels such as latest browser
- Severity scope reflects observed combinations rather than an unsupported universal browser claim
Watch for: A minimal case can demonstrate the rendering difference, but it cannot prove every device, browser, assistive technology, or production integration behaves the same way.
Sources: [bug-report-pack], [mdn-file-browser-bugs], [rfc-2606]
Intermittent retry or timeout defect
Use when: The same bounded action succeeds and fails across attempts, making frequency, timestamps, and correlated sanitized evidence essential.
Record successful and failed attempts separately, keep one fixture and environment stable, note the timeout boundary, and attach redacted logs or traces with capture times and hashes. Severity should reflect measured impact and scope, not the volume of raw logging.
Structure
- Reproduced count never exceeds total attempts and the frequency statement uses the same sample
- Sanitized evidence preserves correlation and outcome while removing secrets and personal data
- A failed retest stays failed and keeps the report open until a later target-version retest passes
Watch for: A small attempt sample does not establish a production failure rate, root cause, provider responsibility, capacity limit, or remediation priority.
Sources: [bug-report-pack], [owasp-logging]
Decide whether the report is ready for triage
A valid file is only a review gate. A human still decides whether the observation is reproducible, duplicate, accepted, deferred, or outside the general bug process.
The report combines several defects, proposed enhancements, or unrelated evidence under one title.
Choose: Split it into one record per observed defect and link related IDs rather than sharing steps, severity, or closure state.
Tradeoff: There are more records to review, but each defect can be reproduced, prioritized, corrected, and retested independently.
Reproduction steps, version, fixture, environment, attempt count, or sanitized evidence are missing or contradictory.
Choose: Keep the report new and gather the smallest missing observation before assigning severity or a target version.
Tradeoff: Triage waits, but the team avoids choosing work from an unrepeatable summary or unsafe evidence dump.
Evidence contains a credential, personal data, private production URL, customer record, or suspected security or privacy impact.
Choose: Stop using the general pack, remove the exposed material where possible, and follow the organization’s private incident and disclosure process.
Tradeoff: The ordinary tracker loses immediate detail, but access, retention, notification, and remediation stay with the qualified incident owners.
An accepted defect is marked closed without a passed retest on the named target version and resolving evidence IDs.
Choose: Reopen or keep the report fixed, repeat the recorded steps against the target version, and preserve both failed and retest evidence.
Tradeoff: Closure waits, but status remains tied to an observed correction instead of a code change or deployment label.
START WITH ONE OBSERVATION
Download the bug report and validate the evidence trail
Open the Markdown or JSON starter, compare the fictional completed example, inspect the closed schema, and run the included validator before adapting the record to one observed defect.
Download the bug report template packThe ZIP is reproduced locally. Public availability, adapted evidence safety, and real report accuracy require separate verification.
Keep broader QA strategy in the test planUse this page for one observed defect. Use the test-plan owner for environments, coverage, suites, gates, traceability, and technical QA strategy.
What a bug report cannot prove
A structured record reduces ambiguity and makes state contradictions visible. Its conclusion is still limited by the reporter’s access, observation, environment, fixture, evidence, reproduction, and the human decisions around it.
- A reproducible observation does not prove root cause, implementation ownership, remediation method, effort, schedule, or priority.
- A duplicate search can miss differently worded, private, archived, or externally tracked reports and should not be presented as exhaustive.
- A severity label expresses current impact and scope for triage; it does not replace incident classification, business priority, or a contractual response level.
- Sanitized screenshots, logs, traces, and hashes improve reviewability but do not independently authenticate the source, completeness, or chain of custody.
- A minimal reproduction can remove the integration, data, load, permission, locale, assistive-technology, network, or provider condition that triggers the real behavior.
- A passed retest proves the recorded result for the named steps, fixture, environment, and version, not universal regression safety or production readiness.
- The pack does not replace a test plan, change request, security or privacy incident process, code review, deployment control, release decision, or operational runbook.
- This ordinary informational article does not grant AI signup credits. The linked product page follows its own current eligibility rules.
Sources and verification record
The same-release artifact is the direct source for the fictional record and validator claims. Current primary documentation supports structured issue intake, minimal reproduction, safe evidence handling, closed schemas, and reserved fictional domains without certifying this pack.
[bug-report-pack] Playcode:Single-defect bug report fictional example
Checked August 1, 2026. Supports: The locally reviewed single-defect record, reserved targets, three evidence references, accepted triage, passed version-bound retest, exact file allowlist, validator behavior, tests, and reproducible archive. Public availability remains unverified until deployment.
[github-issue-forms] GitHub Docs:Syntax for GitHub issue forms
Checked August 1, 2026. Supports: Current official examples of structured issue inputs, including duplicate search guidance, current and expected behavior, reproduction steps, environment details, and additional context. It does not prescribe this JSON record or triage state machine.
[mdn-file-browser-bugs] MDN Web Docs:When and how to file bugs with browsers
Checked August 1, 2026. Supports: Current guidance to search existing reports, test in multiple environments, build a minimal standalone case, and include browser version, expected and actual behavior, steps, and screenshots. It does not verify any bundled observation.
[owasp-logging] OWASP Cheat Sheet Series:Logging Cheat Sheet
Checked August 1, 2026. Supports: Current guidance on useful event context and on excluding, masking, sanitizing, hashing, or encrypting passwords, access tokens, sensitive personal data, connection strings, and other secrets. It does not make evidence safe merely because redacted is checked.
[json-schema-2020-12] JSON Schema:JSON Schema specification
Checked August 1, 2026. Supports: The current released JSON Schema version, Draft 2020-12, used as the declared vocabulary for the bundled closed schema. The dependency-free validator separately enforces cross-record and workflow rules.
[rfc-2606] RFC Editor:Reserved Top Level DNS Names
Checked August 1, 2026. Supports: The reservation of .test for testing examples, which is why bundled fictional targets avoid real customer, internal, or production domains. It does not make a host private or secure by itself.
Bug report template questions
How much detail should a bug report include?
Include enough detail for another person to reproduce one observed defect without contacting the reporter: expected and actual behavior, ordered steps, fixture, version, environment, frequency, impact, and sanitized evidence. Remove speculation and unrelated history. If the minimal case still needs many pages of setup, link a separate safe fixture or technical note.
What is the difference between severity and priority?
Severity describes the observed impact and scope, such as data loss, blocked work, affected users, frequency, and available workaround. Priority is a human planning decision that also considers strategy, dependencies, effort, risk, commitments, and timing. This pack records severity as triage input; it does not assign implementation priority or a service-level deadline.
Should logs and screenshots be attached to a bug report?
Attach only evidence needed to understand or reproduce the observation. Sanitize credentials, tokens, personal data, customer records, private URLs, and unrelated requests first. Record the evidence kind, capture time, safe reference, hash, redaction confirmation, and short note. A suspected security or privacy issue belongs in a restricted incident channel.
When can a bug report be closed?
For an accepted defect, close after a human triage owner names the target version, someone repeats the recorded reproduction steps against that version, the observed result passes, and the retest references evidence captured after execution. Preserve the original failed observation. Duplicate, deferred, and not-reproducible decisions should keep their own explicit reasons instead.
Is a bug report the same as a test plan or change request?
No. A bug report owns one observed defect and its evidence trail. A test plan owns broader quality strategy, environments, coverage, suites, gates, and responsibilities. A change request evaluates and authorizes proposed scope changes. Link their stable IDs where useful, but do not let the bug report approve implementation, commercial terms, testing scope, or release.
Can Playcode turn this template into a defect workflow?
Playcode can help build a bounded workflow around reviewed report, environment, evidence, severity, triage, and retest records. Before operational use, verify server-side access, attachments, retention, audit, notifications, concurrent edits, incident routing, integrations, export, monitoring, backup, recovery, and release ownership with the people responsible for the real process.
BUILD THE REVIEWED WORKFLOW
Turn the accepted report model into a bounded app
Give Playcode the reviewed fields, roles, states, evidence rules, and ownership boundaries. Verify access, attachments, retention, audit, notifications, incident routing, integrations, monitoring, backup, recovery, and release control before operational use.
Build and verify the defect workflowThis informational article does not grant AI signup credits. No evidence authenticity, coverage, priority, remediation, security, privacy, release safety, reliability, compliance, or business outcome is guaranteed.