A bug report has one job: give someone else enough information to reproduce the problem without asking follow-up questions. If the engineer has to come back and say “what browser were you using?” or “can you show me what you clicked?”, the report didn’t do its job.
When you need this#
- Bug reports come in as vague one-liners (“the page is broken”) and engineers spend more time investigating what’s wrong than fixing it.
- The same bug gets reported multiple times because previous reports were too unclear to match against.
- Engineers can’t reproduce issues and end up closing tickets with “works for me.”
What each section is for#
Summary - One or two sentences. What’s broken and where? This is what someone reads when scanning a list of bugs to triage.
Steps to reproduce - The most important section. Write this as if the reader has never seen the product before. Numbered steps, specific URLs, specific inputs. If you can’t reproduce it reliably, say so and describe what you were doing when it happened.
Current behavior - What actually happens when you follow the steps. “I see a 500 error” or “the button does nothing” or “the page loads but the data is from yesterday.”
Expected behavior - What should happen instead. This sounds obvious, but it forces the reporter to articulate the gap clearly. Sometimes writing this down reveals that the “bug” is actually a feature request.
Logs and screenshots - Paste relevant console output, error messages, or screenshots. Use code blocks for logs. A screenshot of a blank page isn’t helpful; a screenshot showing the error message is.
Possible fixes - Optional. If the reporter knows where the problem might be, linking to the relevant code saves the engineer investigation time. If you don’t know, skip this section entirely.
The template#
### Summary
> Summarize the bug encountered concisely
### Steps to reproduce
> How one can reproduce the issue - this is very important
### What is the current *bug* behavior?
> What actually happens
### What is the expected *correct* behavior?
> What you should see instead
### Relevant logs and/or screenshots
> Paste any relevant logs - please use code blocks to format console output,
> logs, and code as it's tough to read otherwise.
### Possible fixes
> If you can, link to the line of code that might be responsible for the problem