How To Report Bugs Effectively

As software engineer, you will write and receive many bug reports over the years. When bugs are reported with low quality, everyone loses, as the reporter will be asked “annoying” questions, the software engineer has to spend extra time to find out all the details, and overall the eventual fix will be delayed.

Here are a few things and steps I’ve found useful or even essential when writing bug reports.

Template

In an old draft of this post, I hadn’t included this, but since then, I came to learn, that a simple template of a bug report, can force you to consider and share important information that you otherwise might have omitted.

Optional short description

Steps to Reproduce

1. Do X
2. Do Y
3. …

Actual Behavior

This is what’s happening

Expected Behavior

This is what should be happening instead

Additional Information

• Logs
• Environment info
• Additional observations
• Minimal reproducible example (MRE)

• The description is optional, because you often would repeat what’s documented later on, but it can be useful to provide some context information.
• The reproduction steps are a huge timesaver for the software engineer, as they don’t have to spend hours reverse engineering the problem state. Of course, sometimes it’s really unclear how to reproduce it or there may not always be clear steps, but even then, explaining what you did, just before the issue, is usually more useful than no information at all.
• Describing the actual behavior is one of the most crucial points of a bug report, because without knowing what actually went wrong, it’s impossible to provide a fix for something.
• Similarly, explaining what your expectation would have been, helps steer the problem solving in the right direction, plus it can highlight a difference in understanding of the feature/tool between the user and the software engineer.
• Providing logs and any other information, can help narrow down the problem scope. In certain cases (like an open source library), it can make sense to request a minimal reproducible example, which then partially replaces or majorly enhances the “Steps to Reproduce” section.

Filling out this structure with the best intentions, will improve the bug report quality by a lot, as it captures all the essential parts for digging deeper into an issue.

Preceding Steps to Take

The following is a collection of steps to check, when noticing issues with (desktop) applications. They were written down, with reports around SFML in mind, so some might seem a bit too specific.

Before you report an issue next time or immediately ask people for help, consider the following steps:

• Make sure that it’s really the application that causes the issue and not some third-party tool. Commonly applications that can cause others to misbehave include various anti-virus software or f.lux and similar software. Try to temporarily disable these other applications to see if the issue persists.
• If you get some form of error message, always, I really mean always, write the complete message down or take a screenshot. The shown information might look like gibberish to you, but more often than not, an experienced eye will be able to tell you exactly, what went wrong, simply by looking at a complete error message.
• Bugs tend to hide in places the developers haven’t thought of, as they have an expectation on how users will or rather should use their software, and when a user doesn’t follow that path, it can sometimes lead to unexpected situations. Always make sure to provide either exact steps to reproduce that issue, or at least the steps you took just before the issue appeared.
• Every application crash creates a dump file on Windows (unless it’s disabled) and is logged in the Event logger (check Windows’ event viewer). The report doesn’t always help, but it might still give the developer an idea when and how an application crashed. Make sure to provide these when possible.
• If you got an error message or error code, it’s highly recommended you first conduct a web search of said error. Often there might already be a solution to what you’re experiencing. Try adding different variations of the search terms and also add the name of the software,
• Before you open a new issue ticket or ask for help on the forum, make sure to use the search function. It will save the developers time and frustration, and makes you look less like a fool.
• Many open source projects have a publicly available chat room, like IRC, Discord, Slack or similar. Sometimes it’s a lot faster to quickly ask in chat, if your issue is a known problem. However, keep in mind that people aren’t just sitting on their computers waiting for someone to join and ask a question. Sometimes it may take 15-30min and depending on the time zone, it might well be that everyone is currently sleeping.
• If you are sure the issue originates from the application, but you haven’t found a solution or anyone else with the same issue, then it’s time to report the issue. However make sure to follow the contribution guidelines. Some teams prefer reports to first be discussed on the forum, before tickets are opened in their issue tracker.
• We’ve already covered a good way to write a bug report above.
• Include as much information as possible in your report, but don’t over do it. Nobody wants to sift through you hundreds of lines of code, to try and find the place where the error occurs, or scrolling through huge error logs. It’s your responsibility as a reporter to narrow down the problem scope, to the best of your abilities.

Advanced Steps

If you’re an experienced developer you can try to take it up a notch:

• Find the latest debug build or debug symbols or build the application in debug mode.
• Run it the application through a debugger, you should now get descriptive names, where the application crashed exactly.
• If the application is open source, you can take a look at the source code and figure out, why at the given point it would cause a crash.
• Still not enough? Open source projects generally appreciate receiving pull requests, so you could try and fix the issue yourself and help make the application better. 😉