Updated: Dec 2, 2020
In the software industry, we see bugs as an error in coding, therefore we can say that a bug is an error that causes either a specific affected component or the entire system to fail to meet the requirements.
To understand the true meaning of what a software bug is, and to avoid the common misconceptions, we will use these definitions:
A human fault – A fault related to a human action, that causes the system to behave in an unexpected way. Clearly, the initial creation of such mistakes is not obvious to the developers. Had they known, they would most likely not have created the fault in the first place.
A software bug – A software bug is a direct result of a human mistake in source code or its design. It represents a problem causing the system to become unstable, producing results that counter user expectations.
A system failure – A system failure is a direct result of a specific bug causing the system to stop functioning at one level or another.
As you can see, every software bug is related to a human mistake. The simple truth is that no matter how good developers are, they will make mistakes. The only remaining question is how those mistakes are reflected in the system once it is in use.
Why writing bug reports is important
Bug reports are a simple way for project stakeholders to indicate that something in the software is not working as expected. Bug reports allow reported software errors to become a long-living document and to manage an incident until its final resolution.
Many teams have abandoned the use of bug reports, as it seems easier to just send an e-mail or conduct hallway conversations. This is bad practice, as those teams lose significant advantages, such as:
The ability to prioritize and determine which bugs should be addressed first.
The ability to track the historical decisions and investigation of each incident.
A central location to manage all incidents related to the product.
The ability to create dedicated metrics that help both the business and engineering teams promote continuous improvement.
Anatomy of a bug report
No matter how many fields your bug tracking system requires, or how much data you try to track, a few key items differentiate a practical and highly actionable bug report from just wasting time on bug reports that lead you on the wrong path or data that might be ignored.
Below are some of the key fields that should be part of any bug report:
Title – The bug title is perhaps the most important piece of information in the incident report as it allows users to get an idea of the type of bug and the area of impact. A bug title should be short (70-90 characters) and informative enough to provide an accurate summary of the overall incident.
ID – An identifier is usually automatically created by the bug management system which is a sequential number for bugs to be easily tracked.
Steps to reproduce – Short, simple and effective detailed systematic actions to be performed to reproduce the bug. A good reproduction scenario will save time as it reduces the need to ask further questions to generate missing information.
Environment variables – To save time and to ensure the bug will reproduce, it is important that the incident report include the environment in which the bug was found (e.g. OS version, hardware type, etc.).
Created by – When the project consists of multiple teams with many team members, it is useful to know who logged each bug.
Severity – Severity can be defined as the impact on the product/feature due to the introduction of the bug. It ranges from a minor impact such a cosmetic issue or a critical impact that can make the entire system unusable. While the severity level can differ from one organization to another, in my experience, the common criteria are based on the following severity levels:
Severity 1 (Blocker) – An error that prevents the accomplishment of essential system functionality, causes loss of unrecoverable data or causes repeated system failures.
Severity 2 (Critical) – An error that adversely influences the accomplishment of essential system functionality without the availability of an acceptable workaround.
Severity 3 (Major) – An error that adversely influences the accomplishment of essential system functionality with an acceptable workaround that is available within a reasonable time.
Severity 4 (Normal) – An error that causes user inconvenience in a specific system flow, without any major impact on other system functionality.
Severity 5 (Minor) – An error that has a minor impact on specific functionality.
Priority - Priority can be described as the urgency to resolve the bug. here are example priority definitions:
P1 (Urgent) – Must be addressed immediately
Critical security issue that compromises customer data.
Critical legal issue that must be addressed as soon as possible.
Critical business issue such as integration with partner’s site not working.
P2 (Major) – Important but does not represent a catastrophe
Major feature/flow is broken.
Major performance issue that impacts the user experience.
Under specific conditions, user data may be exposed.
P3(Normal) – Fix it after you have addressed P1s and P2s
Security issues that are less important with minimal impact on the user.
Functionality that should be improved (cases that don’t fall into P1/ P2 categories).
P4 (Low) – Nice to have
Minor cosmetic issues.
Typos in low importance areas.
Problem with page layouts.
Date created – The date when the bug was reported, usually generated by the bug management system automatically.
Status – This field represents the status of the bug from its creation in the system and until the teams have closed it.
Date closed – This field is also generated by the bug management system automatically when the bug is marked with a specific status e.g. (verified, by design, etc.).
Expected behavior – The expected behavior is a short description of the result we expect after performing the sequence of steps that triggered the incident.
Actual behavior – This field captures the current behavior of the system compared to its expected valid behavior.
Target version – Indication of which future/current version should include the fix of this bug.