Defect Reporting

What a good report contains

• A specific title. “Export to CSV fails for names containing a comma” beats “Export broken”.
• Steps to reproduce, numbered, starting from a known state, with the exact input used.
• The expected result and the actual result, kept separate.
• The environment: application version or commit, browser or OS, which environment (see Environments), and relevant configuration.
• Evidence: the exact error text copied as text, a log excerpt with timestamps, or a screenshot or recording.
• How often it happens (always, intermittent or only once) and when it started, if you know.
• The impact: who is affected and whether a workaround exists. This helps with prioritisation.

Title: Export to CSV fails when a name contains a comma
Version: 2.4.1 (build 1873), staging
Steps:
  1. Create a customer named "Smith, Anna".
  2. Open Customers and click Export CSV.
Expected: a file is downloaded with the name in one quoted field.
Actual: HTTP 500; log shows "Unterminated quoted field" at 10:42:07.
Frequency: always. Workaround: none.

For machine details, $PSVersionTable in PowerShell or uname -a in Bash is a quick start.

Making it reproducible

Reduce the problem to the smallest set of steps that still triggers it. Change one thing at a time, and write down what does not matter as well as what does. See Reproducing Bugs. If you cannot reproduce it, say so, and attach what you do have.

Writing and following up

• Report one problem per report. Link related ones instead of merging them.
• Search for a duplicate first and add your detail there.
• Describe what you observed before you guess at causes, and put guesses in a separate, clearly marked section.
• Leave secrets and personal data out of logs and screenshots. See Secrets Management.
• Retest the fix, add a regression test and update the report.

Severity (how bad is the effect) and priority (how soon to fix it) are different things, and are often set by the team instead of the reporter. Good reports are also useful input for root cause analysis.

Try it

Find a small bug in any application, or cause one in a project of your own. Write a report using the template above, then give it to a colleague who has not seen the problem and ask them to reproduce it using only your text. Improve the report for every question they had to ask.