How to Write a Bug Report

Publication date: 2021-11-13

If you are an IT professional, then you probably participate in the bug reporting process: either you report bugs to some party, or you receive the bug reports. I report and receive them a lot.

For some people, it may be unclear how do others interact with the issues they report, and some reports may have been processed much quicker if their quality is improved. So, I'll explain simple rules I use when reporting issues in any software, be it for my own team or for an external software vendor.

In my opinion, any good issue report should include the following:

  1. The minimal sequence of steps for the engineer to reproduce the issue. Sometimes, it's hard to minimize your steps, or they are even unknown if the issue doesn't reproduce in a stable way. In such case, the descriptions of the last actions you've taken in the software may help.
  2. The report should include the expected and the actual result of these steps. In some cases, it may seem obvious (like not crashing or not throwing an error), but in most cases, it isn't.
  3. If the software has any logging facilities, then the logs from these should be attached. For browser software, the information from the browser console and/or the browser network console may be very helpful. Sometimes, these logs may include private information, so discretion is advised.
  4. For desktop software, always attach a screenshot, if possible. For proficient software users, a screenshot will help them to instantly recognize a piece of software you're interacting with. Sometimes, screenshot may include important clues you wouldn't think of including into the report.
  5. Always include a version of the software you're using. "I use the latest version" isn't enough: for different user categories and different times, "the latest one" may mean different versions! Such reports become old really quick.

Try not to mix several issues into one report (except for cases you think they all are caused by a common root problem). Such mixed reports are really different to process and prioritize, and they will either have to be split into several tasks, or just buried in the tracker forever.

If you need an issue template, then feel free to use the following:

While interacting with the software [Software Name], I've encountered the following issue: [Description of the broken functionality].

Exact steps to reproduce the issue:

  1. […]
  2. […]
  3. […]

Expected result: […]

Actual result: […]

[A screenshot]

Software version: […]

Environment information: […]

[Logs attachment]