Write Bug Reports Developers Actually Read
Learn how to write bug reports developers can quickly understand and act on: use specific titles, clear reproduction steps, expected versus actual results, and searchable evidence. We also cover why neutral language, one defect per report, and honest severity ratings help build trust and speed up triage.
Show Notes
- How to Write a Bug Report Developers Actually Act On - Pearly Quality: https://pearlyquality.hu/articles/bug-reports-developers-act-on/
Chapter 1
Why Developers Skip Your Bug Report
Claire Brooks
Here's a real ticket title from Apache's tracker, bug COCOON 1254. The whole title is "SemWeb." That's it. Imagine opening that on a Monday morning.
Oliver Hart
And it's not a one off. The 2008 study "What Makes a Good Bug Report?" quotes a Mozilla bug, number 109242, titled just "GUI," with the comment, "The page is too clumsy." The researchers surveyed developers and reporters across Apache, Eclipse and Mozilla, and got 466 responses. The finding was a mismatch. Developers said steps to reproduce, stack traces and test cases helped most. Those are exactly the things reporters found hardest to supply.
Claire Brooks
So last time we covered the mechanical ingredients: environment, repro steps, frequency, evidence. Today's question is different. Why does a developer ignore a ticket even when some of that is there?
Oliver Hart
Part of it is human. Pearly Quality makes the point that bug reporting is closer to diplomacy than data entry. You're delivering unwelcome news, usually at an inconvenient time. A fully reproducible report removes the comfortable reply, "it works on my machine." Their argument is that a developer may start by scrutinizing your setup, or your competence, before looking at their own code. That's their interpretation, but it fits the survey. One developer comment in the paper said rude or sarcastic bugs don't help their chances of getting addressed.
Claire Brooks
So neutral facts. Not "login is broken," but what you did and what happened.
Oliver Hart
Right. And Joel Spolsky's framework gives you the skeleton: steps to reproduce, what you expected, what you saw instead. The expected part matters more than people think. What a tester assumes is an error might be intended behavior. Stating the gap between expectation and reality is what defines the defect. Pearly Quality puts it neatly: reproducibility is the whole difference between a defect and an anecdote.
Claire Brooks
Okay, practical habits. Titles first. "Checkout button broken" names a location. A better one says what happened, where, and under what condition. Checkout fails with HTTP 500 when a promo code is applied to a cart with several items. An engineer can triage that without even opening it.
Oliver Hart
Second, one defect per report. Bundle three issues together and, in practice, somebody fixes the easy one and closes the ticket. Third, be honest about severity. Severity is impact, like a crash or data loss. Priority is business urgency. Call a cosmetic misalignment a blocker and you spend trust you'll need later.
Claire Brooks
And paste the stack trace as text, next to the screenshot. Then a developer can search the codebase for that exact error string. The study's authors even mined bug databases for encouraging facts like "bug reports with stack traces are fixed sooner."
Oliver Hart
Which is the whole lesson, really. Make the ticket easy to believe, easy to find, and easy to start on.