Write a focused title and summary

Begin with a title that names the symptom and the component involved. Follow it with a short paragraph that states the expected behavior and the actual outcome in one or two sentences. Avoid phrases such as it does not work. Instead, quote any error messages exactly and note the line or file where they appear. A clear title helps responders locate similar past reports quickly and decide whether they have the right expertise to assist. The summary paragraph then supplies the minimal context needed to understand why the reported outcome matters.

This focused opening prevents the common problem of responders having to ask clarifying questions before they can even begin investigation. It also sets the stage for the rest of the report by establishing a shared vocabulary for the symptom.

  • Include the version of the library or tool that exhibits the problem.
  • Mention the operating system and relevant hardware only if the issue is platform-specific.

Reduce the code to the smallest working example

Create a fresh project or file that contains only the code required to demonstrate the failure. Remove unrelated functions, configuration, and data. Use simple names that describe purpose rather than copying identifiers from the original codebase. If the problem disappears during reduction, restore the last removed piece and test again to isolate the trigger. The process of successive removal forces you to discover exactly which lines participate in the failure and which are incidental.

A minimal example also makes it easier for responders to copy the code into their own environment without first untangling dependencies or project-specific setup. This reduction step is the heart of turning a vague report into one that can be verified and fixed.

  • Place each file in its own code block with a short description of its role.
  • Avoid images of code; paste the actual text so it can be copied and run directly.

Document the exact environment

List the versions of every relevant piece of software, including the runtime, compiler or interpreter, operating system, and any extensions or plugins. Note whether the issue appears only in a specific editor or only after a recent update. This information prevents responders from wasting time on configurations that do not match yours. Environment details also reveal whether the failure is tied to a particular combination of tools that may not be obvious from the code alone.

When the environment is recorded precisely, responders can decide whether they need to replicate it exactly or whether the problem is likely to appear more broadly. This section therefore saves repeated rounds of clarification.

  • Run the standard commands that print version numbers and include their output verbatim.
  • Mention any environment variables or configuration files that differ from defaults.

Provide numbered reproduction steps

Write the sequence of actions required to trigger the bug as a numbered list. Start from a clean state each time you test the list yourself. Include any necessary interaction such as clicking a button or entering specific values. If the problem occurs only after a restart or in a fresh environment, state that requirement explicitly. Numbered steps remove ambiguity about order and prerequisites, allowing responders to follow the same path you took.

Each step should be short enough that a reader can perform it without additional interpretation. This format also makes it simple to verify later whether a proposed fix actually resolves the reported sequence.

  • Keep each step to a single action.
  • Note any timing or order dependencies that affect the outcome.

State expected versus actual behavior

Describe what the code should do according to documentation or common sense. Then describe the precise incorrect result, including any error text, incorrect output, or unexpected state. This contrast tells responders exactly which contract has been broken and helps them verify a fix later. Without an explicit statement of expected behavior, responders may guess at different intended outcomes and therefore test against the wrong target.

Placing the two behaviors side by side also clarifies the severity of the issue and guides prioritization of the report among other tasks.

  • Quote error messages and stack traces in full.
  • If output differs, show both the expected and observed values side by side.

Verify the example before submission

Run the reduced example in a new directory or fresh virtual environment to confirm it still fails. If the problem vanishes during cleanup, the original report contained hidden dependencies. Restart the system or move the files to another machine when intermittent behavior is suspected. Only submit the report once the minimal example reliably reproduces the issue. Verification protects both the reporter and responders from spending effort on a description that no longer matches reality.

A final check also surfaces any accidental omissions that occurred while trimming the example, ensuring the submitted report remains complete and accurate.

  • Delete temporary files and caches before the final test.
  • Confirm that no compile-time or lint errors exist unless they are part of the reported problem.