Free bug report template for development teams

↓ Download Markdown template

The template

Copy this into your issue tracker, Notion, Google Docs, or Markdown file. Delete the fields that don't apply to your project.

## Bug title
One clear sentence describing what's wrong.
Example: "Login button unresponsive on mobile Safari"

---

## Summary
Two to three sentences: what you were doing, what happened,
and what you expected to happen.

**What I did:** [step that triggered the bug]
**What happened:** [the broken behavior]
**What I expected:** [the correct behavior]

---

## Steps to reproduce

1. [First step — be specific, not "go to the page"]
2. [Second step]
3. [Third step]
4. [Observed: the bug appears here]

---

## Environment

| Field           | Value                                         |
|-----------------|-----------------------------------------------|
| Browser         | Chrome 126 / Safari 17 / Firefox 127          |
| OS              | macOS 15 / Windows 11 / iOS 17               |
| Screen size     | 1440px / 375px (mobile)                       |
| App version     | v1.2.3                                        |
| URL / route     | /projects/42/bugs                             |

---

## Severity

- [ ] Critical — app is down or data is lost
- [ ] High — major feature broken, no workaround
- [ ] Medium — feature broken, workaround exists
- [ ] Low — cosmetic or minor inconvenience

---

## Screenshots or recording

[Attach here]

---

## Console errors (if applicable)

```
Paste browser console errors here (F12 → Console → copy errors)
```

---

## Additional context

How often does it happen? Reproducible by others? Workaround?

Field-by-field guide

Title

The best titles name the broken behaviour, not the expected one. "Dashboard doesn't load" is weak — a developer doesn't know what "doesn't load" means. "Dashboard returns 500 error when opened with no projects" is specific enough to suggest where to start looking.

Steps to reproduce

The most important field. Number them. Start from a known state ("while logged in as a member"). Be specific about what you click, what you type, and what you see at each step. If a developer can't reproduce the bug from your steps, fixing it is largely guesswork.

Environment

Bugs that happen on one browser and not another, or on mobile but not desktop, or only on a specific version — these are common. Record the browser, OS, screen size, app version, and the exact URL. A bug report without an environment is a bug report half filed.

Severity

Be honest about severity. "Critical" should mean the app is down or data is being lost — not "this annoys me". Mislabelled severity trains developers to ignore the field. If everything is critical, nothing is.

Screenshot

Attach one even when the bug seems obvious from the description. A screenshot shows exactly what the reporter saw — the layout, the error message text, the state of adjacent UI — without ambiguity about which page they were on or what they were doing.

In BugTrack, you can paste a screenshot directly from the clipboard into the description or comment field.

Common mistakes to avoid

• Vague titles. "It's broken" or "button doesn't work" tells a developer nothing.
• Missing steps. "Go to the page and click it" isn't enough. Start from a reproducible state and be specific about every action.
• No environment. If you don't say what browser you're on, the developer has to ask — and wait for the reply.
• Skipping the screenshot. Even a bad screenshot is faster than a follow-up conversation.
• Mixing expected behavior into the title. "Should show a confirmation dialog" belongs in the body, not the title. The title is for what went wrong.