Free editable template
Bug report template
A useful bug report lets someone repeat the failure without reconstructing your session. This template keeps the starting state, steps and observations together, whether the code came from a person or an agent.
Markdown (.md). No signup. Free to use, edit and share, including at work.
How to use it
- Record the version and environment. A screenshot without the build or browser can leave the developer testing a different situation.
- Start from a state another person can reproduce. Use sample data and write each action in order.
- Separate the expected result from the actual result. Include the exact error where it helps and state how often the problem occurs.
- Describe the impact and a way to verify the fix. Attach only the relevant output, with credentials and personal information removed.
Open the file in any text editor, fill in the brackets, and paste it into your pull request or issue tracker. No attribution required.
Worked example
Example: a report that a developer can repeat
- Title
- Submitting an invalid email clears the message field.
- Environment
- Preview build [commit], [browser and version], signed-out visitor.
- Steps
- Open Contact. Enter “Pat”, “not-an-email” and a sample message. Press Send message.
- Expected / actual
- Expected: show an email error and keep the text. Actual: the email error appears and the message field becomes empty.
- Fix verification
- Repeat the same steps on the fixed build, then send a valid test submission in the test environment.
The full template
# Bug report Title: [action + unexpected result] Example: Submitting an invalid email clears the message field. ## Where it happens App or repository: [name] Version: [commit, build or release] Page or command: [URL or command] Environment: [browser / OS / runtime and version] Account role, if relevant: [role, not credentials] ## Steps to reproduce Starting state: [what must be true before step 1] 1. [first action and sample input] 2. [next action] 3. [action that exposes the failure] Use made-up sample data. Remove passwords, tokens and personal information from attachments. ## Expected result [What should have happened? Link to the acceptance brief if there is one.] ## Actual result [What happened instead? Include the exact error text where useful.] ## Evidence Screenshot or recording: [link] Relevant output: [small excerpt or attachment] Does it happen every time? [always / sometimes / once; number of attempts] Last known working version: [version or unknown] ## Impact Who is affected: [users or workflow] What is blocked: [consequence] Workaround: [steps or none known] ## How to check the fix Repeat the steps above on: [fixed version] Expected observation: [result] Nearby behavior to recheck: [workflow] Checked by: [name and date] --- From Ranex: https://ranex.dev/resources Free to use, edit and share, including in commercial projects. No attribution required.
Common questions
What if I cannot reproduce the bug every time?
Say so. Record how many attempts failed, the time and the conditions you noticed. A report of two failures in ten attempts is more useful than an unsupported claim that it always fails.
Do I need to know what caused the bug?
No. Describe what you observed and how to repeat it. Label any suspected cause as a hypothesis so it does not get mistaken for evidence.
Keep the evidence with the work.
The template helps you describe and review the work. Ranex checks signed evidence against a policy for an exact version of the code.