Writing nice bug reports

I read a lot of bug reports in open source and closed source code projects in my day-to-day work, both big and small. A good bug report does a great job setting the stage for the resolution of an unexpected behavior.

After reading and responding to many, many bug reports over the past year, here are some common characteristics of the best reports I’ve come across:

The bug report has a clear title

The title of the issue should summarize what you’re seeing in a one word sentence. It should be clear and understandable, almost like a good news headline:

✅ Interface builder designable fails to compile in Xcode 9

Sounds a lot better than:

❌ Error when using interface builder

Summaries are thoughtfully written

It sounds trivial, but inspecting other bug reports to make sure that yours isn’t a duplicate is a cool thing to do. If someone else reported your issue, you can save time by not having to write a report all over again! If a new report is required, make sure to note:

*The minimal test case

The minimal test case is the evidence you’re submitting to prove the bug exists. In my opinion, it’s the most important part of the bug report. Your minimal test case should:

✅ Detail a series of easily understandable steps to reproduce the issue.

✅ Contain the the minimal amount of code required to replicate the bug.

❌ If you must attach a sample project to download, this should not be your entire project. The reviewer’s weary soul can’t take it. Isolate as much as you can so that the only remaining code is the code that reproduces your issue.

In short, the minimal test case helps both the person reporting the bug and the person who is responsible for investigating. It forces the reporter to double check that they haven’t inadvertently caused the issue themselves, and it allows the investigator to quickly set up an environment to quickly reproduce the issue.

The report

After providing a minimal test case, the next key thing to do is to provide information about the crash itself. What is the expected behavior versus the actual behavior you’re seeing? It’s possible that your bug might be an expected outcome, and that’s okay. As long as you document the mental model of what you’d expect to happen against what is actually happening, you can help maintainers better understand how people perceive their projects.

As a next step, you might be tempted to take a screenshot of a crash and attach it, but text is the way to go here - especially in open source projects.

Think of the users who are running into the same issue you are - if they ran into the same crash, they’ll likely search for the text of the crash within the project or within a web search. Wouldn’t it be nice if their search matched the exact text of what you wrote in your original bug report? This also makes it easy for future users to make sure they aren’t submitting a duplicate issue.

Including multimedia

GitHub supports HTML detail disclosure elements so you can show and hide large chunks of text. I recommend using them to selectively display a large crash report or stack trace to keep your bug report streamlined.

If a report includes images or gifs, its to complement the bug report and minimal test case - they shouldn’t be used to make up for a lack of either.

The end

It doesn’t matter what language, framework, or platform you’re working in - everyone will appreciate the consideration and care you put into a good bug report!