Minimal bug report template

Getting good bug reports is important. We want to quickly understand and reproduce problems instead of going back and forth with users collecting information that could have been submitted from the beginning.

Many software projects nowadays don’t use specialized bug-tracking software. It is common to rather configure a general-purpose issue tracker or project management software to include bug reports among other tickets.

While having a structured bug reporting form is not always necessary, we still need to collect a few important details on every report. That’s where bug templates come in handy! For example, we can configure a bug issue template on GitHub and even present it as a form for nicer input.

Bug report templates tell users what information should be provided along with instructions for them to follow. My minimal bug report template would look like this:

• Description

  • Briefly describe the problem. What are you trying to do and why?

• Steps to reproduce

  • Provide a list of steps required to produce the error.

• Actual result

  • Describe what happened when you followed the steps to reproduce.

• Expected result

  • What did you expect to happen instead?

• Environment

  • Application version, operating system, browser, etc.

The description is the place in the bug report where users can share an overview of the problem and include any background information about their use case. It is possible that their problem can be solved through different means or that it simply isn’t supported. It provides the context in which the users operate and exposes use cases that perhaps weren’t considered when creating the software.

Steps to reproduce should provide developers with exact instructions to reproduce the problem. However, it can be difficult for users to understand what contributed or didn’t contribute to the bug. People are likely not to even think about “steps to reproduce” when submitting a report. That’s why it is important to include them in the template, although the submitted data might not be ideal.

To get into the users’ minds, one of my favorite thing is to directly ask what the expected result is and how it differs from the actual result. Because not all bug reports are actual bugs, knowing about the user expectations can help us to produce better documentation or improve the user experience in the future.

The last part, the environment, will be context-specific. It is good to provide suggestions on what information we typically need, but not to overwhelm reporters with every single detail. Focus on the things that improve the reproducibility of the reports. Also, help people collect the information required. If you request an application version, tell them where to find it.

And that’s it! While it can be useful to extend the template based on your situation I believe that having a general minimal template is already a great start and it will get you better bug reports.

—

Let me know what you think,

Petr