How to Write a Useful Bug Report

A useful bug report gives maintainers enough information to reproduce or understand a defect. It should include the version, environment, steps to reproduce, expected result, actual result, evidence, impact, and anything unusual about the setup.

Think of a bug report as a compact reproduction package. The report does not need to solve the bug. It needs to make the problem clear enough that maintainers can confirm it, ask a focused follow-up question, or close it with a specific reason.

Quick bug report template

Use this structure when the project does not provide its own template:

1. Summary: one sentence describing the defect.
2. Version: the exact app, library, plugin, or package version.
3. Environment: operating system, browser, runtime, hardware, database, or device details that matter.
4. Steps to reproduce: numbered actions from a clean starting point.
5. Expected result: what should have happened.
6. Actual result: what happened instead.
7. Evidence: logs, screenshots, crash reports, sample files, or console output.
8. Impact: whether the problem blocks work, corrupts data, breaks compatibility, or has a workaround.

The expected outcome is a report that another person can follow. If a maintainer cannot reproduce the problem, the report should still give enough evidence to understand where the failure may be happening.

Start with a precise summary

The title or summary should describe the failing behavior, not only the emotion around it. "App crashes when importing a 4 GB CSV on Windows 11" is more useful than "Import is broken."

Good summaries include the action, affected area, and visible failure. Weak summaries use words such as broken, bad, slow, unusable, or does not work without context.

Keep the summary neutral. A bug report is more likely to move forward when it separates the defect from blame. Maintainers need facts they can test, not pressure to agree immediately.

Write reproducible steps

Reproduction steps are the core of most bug reports. They should start from a known state and use numbered actions. Include setup steps only when they matter.

Useful steps look like this:

1. Install version 2.4.1 on Windows 11.
2. Open the sample file attached to the report.
3. Choose File, then Import.
4. Select the default import settings.
5. Click Start.

Then describe the expected and actual results separately. Do not hide the actual result inside the steps. If the bug only happens sometimes, say how often and what appears to influence it.

Include environment and version details

Many bugs depend on the environment. A crash may happen only on one operating system. A rendering issue may appear only in one browser. A build failure may depend on a compiler, dependency, driver, locale, or hardware feature.

Include details that could plausibly change behavior:

• software version or commit;
• operating system and version;
• browser or runtime version;
• architecture such as x64 or ARM;
• device, driver, or graphics information when relevant;
• configuration files or settings that affect the defect;
• whether the problem appears in a clean profile or fresh install.

Do not dump unrelated system information. The goal is to help maintainers narrow the failure, not to make them search through noise.

Add logs, screenshots, and minimal examples carefully

Logs and screenshots can turn a vague report into an actionable one. Attach the shortest evidence that shows the problem. If a text log is available, paste the relevant lines in code formatting and attach the full log only if the project asks for it.

Minimal examples are especially useful for libraries, command-line tools, parsers, and file-format bugs. Remove private data and unrelated code until the smallest failing case remains.

Check evidence for secrets before posting. Logs may contain usernames, access tokens, file paths, email addresses, API keys, private URLs, or customer data. Redact sensitive values while keeping the technical structure visible.

Separate bugs from feature requests and support

A bug is behavior that fails against the project's intended or documented behavior. A feature request asks for new or changed behavior. A support question asks for help using existing behavior.

This difference matters because maintainers respond differently. A bug report needs reproduction. A feature request needs a use case and tradeoff. A support question may belong in discussions, documentation, or a community channel.

If you are unsure, describe the result you expected and where that expectation came from: documentation, release notes, older versions, another platform, or a standard format. That context helps maintainers decide whether it is a defect.

What not to include

Avoid these common problems:

• vague titles with no affected area;
• screenshots without steps or version details;
• "same here" comments with no new environment information;
• demands for immediate fixes;
• private data, passwords, tokens, or unredacted customer files;
• multiple unrelated bugs in one report;
• security vulnerability details in a public issue when the project has a private reporting path.

If the problem may expose a security vulnerability, look for the project's security policy or private contact path before opening a public issue.

Example fields

Before submitting, read the report as if you were seeing the project for the first time. If a stranger could not reproduce or understand the defect, add the missing detail before opening the issue.