What makes an essential bug report?

What is a “bug report”?

A bug report is a simple and efficient way of communicating that something in the project is not behaving correctly or needs improvement. This may sound trivial, but very often situations arise where the submitted bug report does not have enough information, or the information doesn’t contain key details required to understand or reproduce the issue.

For this reason, someone who has not seen or reproduced this behavior, might not know what exactly is going on.

The goal here is to make a solid foundation for a bug report which can be included in any project and make it easily readable for anyone working on the project. Providing a correct and detailed bug report, which we will cover in the following sections, results in saving a lot of time and effort for your developers.

There are many solid tools and software which can be used for managing a project and writing a bug report, such as “Jira”, “Notion”, etc. Here at PROTOTYP, we’re using Notion as our all-in-one workspace and we use it to write bug reports as well. All examples in this article will be showcased using Notion but the general idea and the point can be applied to any tool that you’re currently using.

Now that we know what the bug report is, let’s see what we need to include in our bug report so the rest of the team can quickly and efficiently reproduce and fix the issue described in the report.

How to write a bug report

Title

Every bug report should have a title. The title of the bug report needs to be short and clear, summarising the issue in a few words. The point is to display the most useful information to anyone on the project.

Consider pointing out to a certain component or a category where the bug occurred so the developers know right from the start what to expect. Avoid describing the entire bug in the title, there is no need to overcomplicate things here, it will only lead to confusion, possible duplicates, and unreadable reports.

A good example of a short and clear bug title would be "Duplicated items are being added to the todo list".

Description

This is the place where you can go to a bit more detail on the bug. Still, try not to overcomplicate it, remember that short and efficient is what we're aiming for. Describe the details that are necessary to understand and reproduce the issue. Avoid including unnecessary and unhelpful details, like describing every single step of the reproduction process. Avoid telling the whole story, the point here is to highlight the summary. Try to mention the frequency of the issue and any necessary circumstances that occurred when you reproduced it.

Priority

How should you determine the priority of a bug? There are many different approaches to this, I found that categorizing bug priorities into the following four levels yielded the best results in addressing the issues in proper order. Therefore, anyone looking at a report can right away know how impactful it is to the project.

These four levels, in ascending order of priority, are:

1. Minor - this priority is set on bugs that affect a very small portion of the userbase and that do not have a noticeable negative impact on the UX. Minor priority does not reflect the complexity of the issue, but rather how it affects the UX or the presentation of the project. An example of a minor bug would be if a “search button” is not aligned properly with the “search bar”.
2. Major - we use this priority for bugs that are easily reproduced but there is a "workaround" for them. For example, navigating to “Shop” can be done through two buttons, but one of those buttons is not redirecting correctly. Yes, the user can navigate to the “Shop” via the second button, but we should still address the first, non-functioning button when the higher priority issues are resolved. This has a noticeable negative impact on the user experience and the application flow and should be handled if there are currently no bugs with a higher priority.
3. Critical - used for bugs that affect most (if not all) of the userbase and have a highly negative impact on the user experience. The functionality is not working and something is seriously wrong. These issues need to be addressed as soon as possible since the feature is rendered unusable. In some cases, “minor” bugs can be turned to "critical" (such as a clumsy typo or a misplaced button on a released project, making everyone involved seem a bit like amateurs).
4. Blocker - a major functionality on the application is not working or it is causing a large data loss. As the name suggests, the users and testers are blocked from a vital part of the application. These issues are top priority and should be fixed before any other issues that are currently reported.

The term "severity" can also be mentioned quite often in this section, which emphasizes the impact of the bug on a project, while “priority” is used as a method of distributing and assigning bugs to developers.

As it is emphasized earlier, we like to keep it short, simple, and efficient around here, so we bundled severity and priority together and settled on calling it "Priority".

Environment

Bugs and applications behave differently in different environments. In this section, the setting in which the bug was reproduced should be summarized.
The list may vary depending on the project and your workflow, but most of the time that list consists of:

1. Device (PC, Mac, Android, iPhone, etc.)
2. OS (Windows 10, macOS Catalina, Android 10, etc.)
3. Browser (Chrome, Safari, Firefox, Opera, etc.)
4. Application version
   

A good bug report needs to contain detailed information about the environment where the bug occurs since it helps a lot with reproducing and fixing the bug.

Additionally, I strongly advise good application versioning as it proved helpful to both our QA & development process. Without versioning a project in development, people who are working on the project may sometimes be on different versions of the project, which leads to reporting bugs that may have already been fixed and addressed. It can also disrupt communication until everyone is on the same version of the project.

Steps to reproduce

List of necessary steps that the developer needs to take to reproduce the issue. Make sure to avoid using unnecessary steps, since we want to keep this short and readable. Also, bundle together actions that make sense to be bundled together, for example, "Click on my profile -> log out", as this will appear more readable in some larger reports.

A good example of steps to reproduce would be:

“User avatar doesn’t change after reload”

1. Open app -> My profile
2. Click on "Change avatar"
3. Select avatar -> Save changes
4. Reload app
   

Ordering steps in this way helps developers so they don't waste time on reproducing simple bugs.

Expected behavior

The result that was expected to happen and should happen after fixing the bug.

Actual behavior

The result contains a bug that was reproduced by the tester or the user.

These two sections are very important since they accurately compare the expected and actual results noticeably. It helps the developer working on it to exactly know why this is a bug and how it should work after fixing it.

Attachments

Depending on the nature of the issue, bugs can be described in more detail and fixed more efficiently by providing additional resources - text files, JSON data, screenshots, videos, etc. This helps with showcasing its reproduction or actual behavior.

Keep in mind not to take long and unnecessary screen captures of the bug, since we want to save time with this method. Also avoid cramming too much data in this section of the bug report and remember, this DOES NOT replace the need for the written section of your report.

Only provide essential information with attachments and make sure to "label" them if you need to provide multiples.

Also, don't forget about logs, I assure you that your developers will love it if you include these when needed.

That’s a wrap!

There we have it, a strong foundation on which you can build and improve upon depending on the needs of your project. Always remember to KISS (“Keep it simple, stupid”) and you will make the QA process of bug reporting on any project streamlined and intuitive.

What is your approach to reporting bugs? Feel free to let me know if you have any questions or ideas for improvement on this topic!

Thank you for taking the time to read this post. Feel free to share your thoughts about this topic in the comments or drop us an email at hello@prototyp.digital. 😄