Basic rules for creating a bug

This page describes some basic rules that must be followed when reporting a new bug

Introduction

Sometimes creating a bug can be much more complicated than you can think. Providing all the necessary information can help developers to accelerate the bug fixing and as a result of that can help us to improve the project's execution time. This section gives you some basic rules when reporting a bug.

Describe the problem in detail

The problem description is one of the most important parts of bug reporting. With a clear and detailed description of the problem, we can avoid misunderstandings and the common back-and-forth discussions when the developers are trying to understand what they must fix.

Sometimes, you can see bugs with descriptions like "I clicked the button, and it didn't work". But descriptions like this can lead us to confusion.

Some questions that can raise from the previous example are: Which button? What did you do before clicking the button? What input data had you provided?

And additionally, what do you mean by "it didn't work"

The button is not clickable, the application crashes when you click the button, the application gets stuck, or you have an error message saying that something went wrong.

It's important to provide all the relevant information that can help the developers to understand the problem. Provide logs, screenshots, and everything that you think would be helpful. Provide a concise description and all the steps required to reproduce the issue.

Provide a minimal reproducible example

Probably you are thinking that “it's hard to create an isolated example”, and yes, sometimes is hard to create a minimal reproducible example. But in cases where it’s hard, you can discuss it with the team and if it's hard we can provide them with enough information to help them reproduce the bug without the need of creating a small example, but in most cases creating a minimal reproducible example, it's necessary, and most important is a must.

Why it's so important to have this? because the developer can fix the bug much more easily if they can easily reproduce the issue on their own machines. They can trace the issue and try to identify the root cause faster.

Remember that a "reproducible example" is a set of instructions that makes the bug happen every time. It’s a small isolated program that allows the developers to reproduce the issue every time he executes the example.

With a small example, you avoid the developers to be asking you about environments, configurations, or anything that is required to reproduce the issue in the main application with all the complexities it implies.

With a minimal reproducible example, you won’t probably need to do any special configuration, use Databases, and mainly you will remove all the complexity that reproducing the issue in a bigger application will imply.

This is not just help for the developers, in the end, this will help developers to reduce the bug fixing time.

Always provide the Acceptance Criteria

A common situation when fixing bugs is when as a developer you do a fix and the one who created the bug tells you that what you did wasn't what he was expecting you to do.

This is a normal scenario that most of us have seen in the past. This is the case of a mismatch between expectations.

How can we avoid these mismatch situations? Adding good Acceptance Criteria to our bugs.

If you expect the button to raise an error message, to change the screen color, or to open a new screen, you must add that information to the acceptance criteria of the bug. You should give enough information to tell the developer what you are really expecting from the bug fix.

The developer doesn’t know what you expected to happen or wanted to happen unless you tell them.

You must be clear and concise in describing your acceptance criteria, giving enough information for the developer to understand what you are expecting from the bug fix.

Don't forget the Priority and Severity

Besides the description, a minimal reproducible example, and the acceptance criteria, it’s also important to define the right severity and priority of the bugs.

The severity is the value that helps us to understand how severe a bug is and the overall impact it has on the application.

On the other hand, the priority tells us about the order in which the bug should be resolved based on the severity.

Both values will help developers to organize the job and to know which bugs have more impact and are the most important for the application.

Put yourself in the developer's shoes

Think as if you were the developer who will work on the bug. Think about all the information you will require to try to fix it. Try to anticipate what you think they will need to know and give them all the information you think you will need in their position.