repro.fyi
A minimal repro is the smallest set of steps that reliably reproduces your bug.
Why bother?
Minimal repros are valuable for a couple reasons:
1. Aiding debugging. Minimal repros are a boon for fixing bugs. They save engineers a lot of time.
2. We know when the bug is fixed. Without it, you may find yourself chasing phantoms.
How to make one
Start fresh: Create a new file or sandbox. Add only what's needed to show the bug. If you can't reproduce it in isolation, that tells you something — the bug is in the stuff you left out.
Or strip down: Copy your project, delete half. Still broken? Delete half again. Fixed? The bug was in what you deleted — put it back, delete the other half. Repeat until nothing's left to remove.
When to ask for help: Keep isolating until you hit someone else's black box — a platform, library, or API you can't see inside. That's when you've earned the right to ask.
Good vs bad
Chrome, macOS.
To Repro:
- Open
/dashboard- Click "Export"
- Select CSV
Expected: File downloads.
Actual: Console shows
TypeError: Cannot read property 'map' of undefined
vs.
"File exports are broken, please fix ASAP"
Common mistakes
- Sharing your whole codebase. The goal is to get someone into the bug as fast as possible. A fresh sandbox with just the error beats a link to your repo.
- Skipping the steps. "It's broken" isn't actionable. Include a list of numbered steps to repro the bug.
- Not including versions. Or not upgrading first. Half of all bugs are fixed in the next release.
- Browser extensions. Try incognito mode before reporting. Extensions break more things than you'd think.
Further reading
- How to Report a Bug — Tom MacWright's guide to polite bug reporting
- SSCCE — Short, Self-Contained, Correct Example
- How to Report Bugs Effectively — Simon Tatham's classic guide