How to write a good bug report
In this post, I talk about fantastic bugs and how to report them so developers can find and fix them.
A good bug report should reduce back and forth between bug reporter and developer.
You should give as much info as you can, It will result in faster resolution because developers will have enough info to triage, investigate and eventually debug.
If the project has a bug report template, use that to report your bug. Most projects ask users for critical info which helps them triage and debug faster.
Do’s and Don’t s when writing a bug report.
Things to do.
- give detailed info, like what is happening, what was expected
- give steps of reproduction, a video is better but sometimes steps to reproduce is enough
- fill out as much info you can, more the better.
Things NOT to do
- Just saying “This thing is not working for me”
- Single line title with no description and reproduction steps
- Ambiguous title with big paragraph and no structure
- Steps of reproduction are mixed with description
- Missing or partial steps of reproduction
Here are few things developers can do to get detailed bug reports
- Make it easy to report a bug, add bug report template which collects essential details required to triage and debug.
- Empower users to submit good bug reports, make it easy and intuitive to create a good bug report.
- You should not ask for things which you can automatically detect and attach in a bug report. e.g. account info when the user is logged in and sending a bug report
- Add instrumentation, when you think you have enough, add some more. you will be glad when you have to debug some obscure bug
- Use error tracking tools like BugSnag or Sentry, I have lost count of times when Sentry saved the day for me
Further Reading
- Mozilla Bug report writing guidelines - Detailed instructions on how to write a good bug report
- How to Write a Bug Report by Ruby Garage