How to Write a Reproducible Bug Report

A bug report is complete when another tester or developer can reproduce the failure without first asking for missing context. The durable essentials remain a precise summary, ordered steps, expected and actual behavior, environment details, and evidence tied to the failure.

What has changed is the submission workflow: teams can now encode those essentials in structured forms instead of relying on memory. GitHub’s issue-form documentation describes configurable inputs, validation rules, uploads, default labels, and required answers, although the feature remains in public preview and may change.

Write for reproduction, not recognition

A screenshot may make a problem recognizable, but recognition is not reproduction. The ticket must preserve the conditions and actions that produced the failure so another person can observe the same result and begin isolating its cause.

Atlassian’s bug-report template identifies severity, environment, reproduction steps, and expected versus actual results as key report fields. That structure is a stronger starting point than a narrative reconstructed from memory.

Reduce each ticket to one observable problem. If a checkout page rejects a valid card and also displays a misaligned button, those are usually separate defects: they may have different causes, owners, consequences, and release decisions. Combining them makes it unclear what a successful fix must change.

Build the report around six decisions

The following sequence gives the recipient enough information to reproduce, evaluate, and route an issue. Field names can vary between trackers, but each decision should remain visible.

Summary: name the affected area, triggering condition, and visible failure. “Checkout fails” is vague; “Checkout returns an error after a valid card is submitted” distinguishes the feature, action, and outcome without guessing at the cause.
Environment: record the application build or commit, operating system, browser or device model when relevant, account permissions, configuration, locale, and network conditions that may affect the result. Include variables that identify or constrain the test setup, not an indiscriminate hardware inventory.
Preconditions: state what must already be true before the first action. A signed-in test account, an item in the cart, an enabled feature flag, or a particular saved record may all determine whether the sequence works.
Steps to reproduce: use a numbered sequence with one action per step. Supply exact input when it matters and begin from a state that another person can establish.
Expected and actual results: describe both as observable behavior. Base the expected result on a requirement, accepted design, established product behavior, or another identified reference rather than the author’s preference.
Evidence and impact: attach the smallest useful set of logs, screenshots, recordings, traces, request identifiers, or crash references. Explain which workflow is affected, who encounters the problem, and whether a workaround exists.

A compact template can therefore use these headings: Summary; Build and Environment; Preconditions; Steps; Expected Result; Actual Result; Reproduction Rate; Evidence; User Impact; Workaround. Ownership, labels, severity, and priority can remain separate tracker fields rather than being buried in prose.

Make every reproduction step executable

Begin from a known state and stop at the first point where behavior diverges from the expectation. Replace “try to pay” with the controls selected and input supplied; replace “it sometimes breaks” with the number of observed failures and total attempts.

As a hypothetical example, the ticket could record three failures across five attempts on a specified build. That observation does not establish that the defect affects 60% of users: it describes only a small test sample under the stated conditions and should not be generalized to production traffic.

If changing one condition removes the problem, preserve the comparison. “Fails on Wi-Fi but completes on cellular data with the same account and build” is more diagnostic than listing the original connection alone. A reduced test case that removes unrelated data or actions can also narrow the investigation.

Chromium’s reporting guidelines request detailed replication steps, expected behavior, useful screenshots, cross-browser checks, and a simplified test when one can be created. These elements reinforce the distinction between evidence that supports reproduction and an attachment offered as a substitute for explanation.

Attach evidence that answers a question

Choose attachments according to the failure. A recording can preserve timing, animation, focus, or gesture behavior; a screenshot can capture a visual state or exact message; logs and traces can expose events that the interface does not show. Add a timestamp or correlation identifier when it connects the evidence to a particular attempt.

Trim irrelevant material without removing context needed to interpret the result. Before uploading, remove passwords, session tokens, personal data, private messages, and unrelated customer records. Sensitive diagnostic material that is essential to an investigation belongs in the team’s approved restricted channel, not a broadly visible ticket.

Do not leave an attachment unexplained. State what the recipient should notice and at which step it occurs—for example, “The recording shows the Submit control becoming disabled after step 4 while the request remains pending.” The written account then remains useful if previews fail or files are archived separately.

Separate impact, severity, and priority

Impact describes the observed consequence: which workflow fails, which users or roles encounter it, whether data is at risk, and whether a workaround exists. Severity classifies the consequence under the team’s definitions. Priority is a scheduling decision that may also reflect release timing, reach, contractual obligations, and available engineering capacity.

The author should document observed impact and propose a severity only when the organization has explicit criteria. Declaring every blocker “urgent” or inserting a release deadline into the description does not replace triage. A specific impact statement gives decision-makers better information for setting priority.

Keep suspected causes separate from verified results. “The request fails after the token refresh event” describes an observation; “token refresh code causes the failure” makes a causal claim that requires investigation. Label a hypothesis as such so it can guide debugging without prematurely narrowing the search.

Use forms without turning them into questionnaires

A template works best when it requests information the team actually uses and removes fields that collect noise. Required inputs suit stable essentials such as current behavior, reproduction steps, and software version. Logs, screenshots, hardware details, and network information can remain conditional when they do not apply to every defect.

Required does not mean exhaustive. Forcing every author to provide a device purchase date, unrelated specifications, or large raw logs encourages filler and may introduce privacy or security risks. Make a field mandatory only when its absence routinely prevents reproduction, triage, or routing.

Forms also need an escape route for defects that cannot yet be reproduced reliably. In that situation, preserve the exact observation, environment, time, evidence, and attempts already made; mark the reproduction status honestly instead of inventing a deterministic sequence.

Run a final handoff check

Read the completed ticket as if you had no access to the author’s screen, memory, or conversation. Confirm that the named build exists, the preconditions lead into the first step, every action is executable, and the actual result clearly differs from the expected result.

Can another person establish the same starting state?
Are exact versions and meaningful configuration differences recorded?
Does each numbered step contain one unambiguous action?
Is the reproduction rate tied to a stated number of attempts?
Does every attachment have a defined purpose and contain no exposed secrets?
Is observed impact separated from suspected cause and scheduling priority?

If the answers are available from the ticket alone, the report has done its job. “Perfect” does not mean long or ornate; it means the next person can reproduce the failure, judge its consequence, and begin a useful investigation without reconstructing the test through follow-up questions.

A Perfect Bug Report Lets Someone Else Reproduce the Failure