A bug report is a record of unexpected software behavior: what someone tried to do, what happened, what should have happened and the conditions needed to investigate it. Bug reporting is the process of collecting that evidence, sending it to the responsible team and following the outcome.
Good bug reporting best practices cover both the report and the workflow around it. A detailed description can still stall without an owner; a fast triage queue can still waste effort if it cannot distinguish observations from guesses. This guide covers reporting, prioritization, tools, resolution and measurement.
1. Describe the failure before suggesting its cause
Start with an action and an observed result. “Adding a second attendee removes the first attendee from the invitation” is more useful than “The database is broken.” The first describes behavior an investigator can check. The second assumes an explanation that has not been established.
Write a brief note while the details are available: the task, action, visible outcome, time, relevant environment and any exact error text. Preserve the starting state where practical before trying again. Clearing data, changing several settings or repeating an action that creates records can destroy the evidence you need.
Include the expected result and its basis: a documented requirement, supported workflow or previously verified behavior. If the expectation is uncertain, say so. A report may turn out to be a defect, a configuration problem, a documentation gap or a feature request; it is still useful to record the customer’s task.
Describe the actual result in observable terms. A frozen interface, a closed application and an HTTP error are different observations; avoid calling all of them a crash.
Mozilla’s bug-writing guidelines emphasize clear summaries, precise reproduction steps and separating observations from speculation. Apply that distinction even when the underlying system is unfamiliar.
For a customer report, ask what the person was trying to do and where it failed. Support can add the technical investigation later. Do not make knowledge of a console, API or database a condition for receiving help.
2. Use a short core format and relevant conditional fields
Collect a descriptive title, starting conditions, numbered steps, expected and actual results, environment, frequency, impact and evidence. Give unknowns an explicit value such as “not yet tested” so a blank field does not look like a confirmed absence.
Keep the customer form manageable. An internal engineering handoff can add build identifiers, diagnostic references and investigation notes after support has reviewed the original report.
| Core detail | Question it answers | Useful check |
|---|---|---|
| Title and task | What action failed? | Names the feature and observed failure |
| Starting state and steps | How can someone investigate the same sequence? | Includes required role, settings or test data |
| Expected and actual result | What behavior differs from the expectation? | Separates the two and includes exact error text |
| Environment | Where did it happen? | Records relevant app, browser, OS or device versions |
| Frequency and impact | How often was it observed, and what work is blocked? | Uses known attempts and states untested scope |
| Evidence | What supports the description? | Accessible to the investigator and linked to the relevant attempt |
A useful title names the affected area and the unexpected result, adding a condition only when it distinguishes the issue. Leave out proposed fixes, exaggerated urgency and lists of unrelated symptoms.
| Weak title | More useful title | What changed |
|---|---|---|
| Attachments broken | Uploaded PDF downloads as an empty file after success message | The action and discrepancy are visible |
| Fix the database | Saved notification preference returns to its previous value after reload | Describes behavior instead of an unverified cause |
| App is very slow | Opening a large conversation delays the reply editor | Identifies the affected task; measurements belong in the report |
Tailor the conditional fields to the type of failure rather than requesting every technical detail from every reporter:
| Issue type | Relevant context to consider | Do not assume |
|---|---|---|
| UI or layout | Viewport, zoom, display scaling and content that changes the layout | Every affected user has the same screen size |
| API or data | Endpoint and method, API version, sanitized input, response and correlation identifier | The reporter knows internal database or server versions |
| Mobile crash | Device model, OS and app build, permissions, foreground/background sequence | A closed screen proves the whole app crashed |
| Performance | Measured action and duration, data size, cache state, observed or simulated network conditions | A speed test alone describes the application’s bottleneck |
Use our bug reporting format guide for field-by-field examples and copyable bug report templates for blank formats. Require an extra field when it supports a real decision, rather than because the tracker can store it.
3. Record reproducibility honestly
Write steps from a known starting state, using the interface labels and input that matter. Another team member should be able to attempt them without reconstructing your session from a video. When feasible, ask a colleague to follow the written sequence without coaching; their questions often reveal missing inputs. If several routes reach the same state, document the one you actually used.
If the issue is intermittent, record observed attempts and outcomes. “Failed twice in five attempts with the same test file” gives more information than “sometimes broken.” Include event times and time zones so an engineer can correlate the report with relevant diagnostics.
Preserve the original conditions before testing alternatives. A private browsing window, different account or cleared cache changes the environment; it is a comparison test, not a universal starting requirement. Record what changed and whether the issue still occurred. Change one relevant condition at a time: “The same file downloaded correctly in the second browser tested” establishes an observed difference, not proof that the browser caused the failure.
For a suspected regression, name the last version verified to work and how you checked it. If a customer remembers it working but no earlier build has been tested, label that as reported history. Do not present an assumed release boundary as established evidence.
4. Attach evidence that answers an investigation question
Use a screenshot for a static state, a recording for a sequence and a relevant diagnostic reference for an underlying event. Introduce each attachment: what it shows, which attempt it belongs to and the important timestamp. Written steps should remain useful without watching the entire recording.
Logs can support an investigation without proving the cause. An error appearing near the failure may be related or incidental. Keep the exact message and time, then separate the observed evidence from the explanation still being tested.
Use approved test data where possible and review files before sharing. Chrome’s Network reference describes sanitized HAR exports that omit certain sensitive headers. That does not establish that every URL, request body or response is safe to share. Review the contents and use the team’s permitted destination. Opening developer tools after the event does not recover earlier requests, so ask for the smallest useful capture of a new attempt rather than an entire session by default, and check that the recipient can open the links.
Screendesk adds recordings and visual support to an existing help desk. Browser and device details accompany recordings; console and network context require developer tools on a supported plan and the relevant capture setup. A recording of another application or a mobile camera video does not automatically include that application’s browser logs.
Worked example: from a vague complaint to a finished report
Illustrative example: all details below are fictional. A customer reports “Attachments broken.” The support agent’s first note is more specific: “Uploaded a sample PDF to a test ticket. The page showed Upload complete, but downloading the attachment produced an empty file.” It describes a disagreement between the displayed result and the retrieved file without guessing whether the browser, storage service or upload request caused it.
The starting state is a test workspace, an existing ticket, a user permitted to add attachments and a known-good sample PDF. The steps are:
- Open the test ticket and select Add attachment.
- Select the sample PDF and confirm the upload.
- Wait for the Upload complete message.
- Download the new attachment from the ticket.
- Check the downloaded file’s size and attempt to open it.
The impact statement stays within what was tested: “The tested upload route cannot provide a usable attachment. Only this file and test workspace have been checked. No data-loss scope beyond the downloaded attachment is confirmed; workaround not yet tested.” That is more useful than “Critical, all users affected” when broader scope has not been investigated.
Title: Uploaded PDF downloads as an empty file after success message
Environment: Demonstration app build 4.3; test workspace; desktop browser
Starting state: User can add attachments; known-good sample PDF supplied
Steps: Add the PDF to the test ticket, wait for success, download it,
check its size, and attempt to open it
Expected: Downloaded PDF retains the original content and opens
Actual: Success message appears; downloaded file has zero bytes
Reproducibility: [Record actual attempts; not supplied in this example]
Impact/scope: Tested attachment unusable; wider scope unknown
Evidence: [Sanitized capture and relevant timestamps]
Investigation: [Comparisons performed; assumptions labeled]
Owner/next action: [Triage destination]
Verification: Repeat with the supplied file in the corrected build
5. Triage impact, scope and urgency separately
Severity describes the effect of a defect under your team’s policy. Priority describes its relative urgency for action. Neither should be assigned from the reporter’s frustration alone.
Ask what task is blocked, whether data or access is affected, which users or environments are known to be affected, how often it occurs and whether a workable alternative exists. Then consider release commitments and the cost of delay. A rare issue with serious consequences can require attention even when its known scope is small.
Microsoft’s Azure Boards guide treats severity and priority as distinct fields and documents process-specific choices. Use your own team’s definitions; another product’s labels do not set your response commitments.
| Observed report | What triage should establish |
|---|---|
| A task is blocked | Importance of the task, known scope and verified workaround |
| Unexpected data behavior | Nature of the change, affected records and appropriate restricted escalation |
| A visible defect | Whether appearance affects completion, understanding or accessibility |
| An intermittent failure | Known attempts, conditions, timestamps and new evidence needed |
Keep independent failures in separate engineering reports so each can have an owner and verification outcome. Link related issues and customer cases. When a duplicate is confirmed, preserve new conditions and evidence in the existing investigation instead of discarding the report.
6. Give every stage an owner and an exit condition
Define the route from incoming report to triage, investigation, proposed fix, verification and closure. The exact states depend on your tracker. What matters is that a person owns the next action and everyone understands what each state means.
Separate ownership of engineering investigation from customer communication. Support may continue updating the customer while engineering investigates the linked issue. Record the relationship so a developer’s comment is not mistaken for a customer-ready explanation.
Bug triage and handoff checklist Report / linked customer case: Known task, failure and affected environment: Evidence reviewed and accessible: Reproduction result / unknowns: Related investigation or duplicate decision: Impact, severity and priority rationale: Next action / owner / review point: Customer communication owner: Proposed fix version, when available: Verification conditions and recorded outcome: Closure reason and follow-up:
Do not equate a merged change with a verified customer outcome. Repeat the failing task in the appropriate corrected version and check the expected result. If the issue is deferred, duplicated or not reproduced, record that reason rather than implying a fix.
Microsoft’s bug-management documentation includes verification and closure reasons. Your team should agree how to handle a failed fix and a later regression, then follow that policy consistently.
7. Choose tools for the evidence and handoff you need
A basic tracker may be sufficient when it can hold a useful description, evidence, ownership and status. More complex workflows may need permissions, searchable categories, integrations and reporting. Evaluate those requirements against actual cases.
Before filing, search the appropriate tracker for an existing report, following that project’s policy. For GitHub, the official issue-creation guide explains repository issues and available templates, and the template documentation distinguishes Markdown templates from structured issue forms. Required inputs cannot guarantee an accurate report, so allow honest unknowns. For Jira, use our Jira bug report guide to map details to your configured form. Legacy TFS users should check the deployed version’s documentation; current Azure Boards behavior is process-dependent.
If a tracker sends Slack or Microsoft Teams notifications, test what information is sent and what action the recipient can take. A notification is not a substitute for a recorded owner. Check permissions and error handling when evidence crosses between help desks, chat and engineering tools.
Begin automation with a narrow, testable rule. A rule can route an issue by component or alert a triage queue; it should also handle unknown categories and unavailable owners. Inspect the saved report after submission so formatting, links and assignment work as intended.
8. Measure report quality and waiting time
Measure the parts of the process you can improve. Resolution time alone combines many factors, including complexity, release schedules and priorities. A universal 24-hour fix target does not establish whether reports are effective.
| Measure | Definition to agree | What it can reveal |
|---|---|---|
| Reports needing clarification | Reviewed reports missing agreed core information / reviewed reports | A confusing field or unsupported evidence requirement |
| Time to first triage | Receipt to the first recorded triage decision | Waiting before investigation begins |
| Reproduction status | Confirmed, intermittent, not reproduced or not yet attempted | Where more conditions or evidence are needed |
| Fix verification outcome | Pass or fail among proposed fixes actually checked | Gaps in fixes or their acceptance conditions |
| Aging by stage | Open reports grouped by state and age | Ownership and handoff bottlenecks |
Compare similar issue types and periods, record your definitions and inspect representative reports. A higher fix rate can reflect easy cases rather than better reporting; a changing severity mix can reflect classification changes. Ask investigators which missing detail would have helped, then adjust the form or training.
Frequently asked questions
How do I report a bug if I cannot reproduce it?
Describe the observed event, environment, time and available evidence. State which later attempts succeeded or failed, and what remains unknown. Submit through the appropriate channel with enough context for triage; do not invent a repeatable sequence.
What belongs in a report-a-bug form?
The task, failure, expected result, conditions or steps, relevant environment and impact. Make technical attachments conditional and allow unknown details. Use a shorter customer intake form and enrich it for engineering.
Does a detailed report guarantee a fast fix?
No. It supports investigation and verification, but the cause, risk, priority and release work still need to be assessed. Track the next action and communicate confirmed progress.
