The ultimate guide to bug reporting

Software bugs are the bane of software development. Pesky and evasive (like their insect counterparts), they only get in the way of a developer’s goals.

A bug will impede the functionality of a piece of software, causing it to operate contrary to the developer’s vision.

To reduce the number of bugs and therefore improve the software’s performance, monitoring and recording them is essential.

That way, developers can systematically clear their software of defects.

This practice is called bug reporting. If you’re unsure how to start, don’t worry, you’re in the right place, as this article is the ultimate guide to bug reporting.

What is bug reporting

As a general rule, you want as few bugs in your code as possible. A bug is a defect within the software that prevents it from functioning as required.

To remove bugs, developers practice bug reporting—the process of tracking and categorizing errors.

Here’s how Bugherd defined bug reporting:

In other words, a bug report is a detailed description of a bug. It’s a developer’s primary tool when debugging, as the bug report should contain all relevant information.

In fact, the main goal of a bug report is to help the developer get to the bottom of the issue and resolve it.

With that in mind, there are certain characteristics that constitute a good bug report, whereas other elements aren’t as useful.

The graph below illustrates both:

Ideally, with a quality report, bugs won’t persist, and developers will be able to fix them quickly to make sure the software functions properly.

Furthermore, a bug report should be a place of collaboration—a medium for QA testers and developers to work together to solve issues.

Finally, bug reports must contain all the necessary information for debugging. This includes network specifications, steps to reproduce the event, screenshots, etc.

Without these crucial elements, the bug report isn’t worth much.

To streamline this process, it’s a good idea to compose a standard template. That way, you’ll have set guidelines for writing bug reports.

Here’s an example of a bug report:

As you can see, the report is full of details, containing the bug’s priority, the version it affects, the environment in which it appears, a description, and visual proof.

This example clearly displays all the classical elements a bug report should contain.

What is the bug life cycle

Broadly speaking, there are two types of bugs: open and closed, meaning that a bug is unresolved or resolved.

However, a bug actually experiences a lengthy sequence of states between these two key stages, called the bug life cycle.

For a visual representation, look at the graph below:

A bug’s initial stage is new—the moment when it is identified and reported.

Following this, the bug is assigned. You, the team lead, will assign the error to a developer for fixing.

The developer begins analyzing it and working on debugging. With that action, the bug is now open.

However, your developer might determine the bug is invalid. In that case, they can defer, reject, or declare it either a duplicate or not a bug.

Deferring a bug means postponing addressing it until the next software release. This is reserved for unimportant, minor bugs.

If the developer rejects a bug, they decide it’s not a genuine defect and doesn’t warrant fixing.

A bug is named a duplicate if the developer notices the same bug was already reported previously.

Not a bug is a particular classification for defects that don’t affect the software’s functionality. In other words, if the functionality isn’t compromised, it’s not a bug.

Let’s return to the open bug and assume it is indeed valid. The developer will correct the error, and the bug becomes fixed.

After resolving the issue, the bug is pending retest—a tester must validate the developer’s solution.

The next step is to retest, which is when the tester begins testing the solution. There are two possible outcomes.

If the software is still defective, the bug is reopened, and the developer must start debugging again.

However, if the test is successful, the bug is verified—the tester confirms the bug is no longer in the software.

Lastly, when the bug no longer exists, it can finally be referred to as closed.

Why is bug reporting important

Without bug reporting, your software runs the risk of not performing as it should.

There can be minor issues, such as some visuals not loading correctly, but you can also be dealing with something as major as disabling registration on iOS devices.

And you wouldn’t want to risk alienating all of your Apple users just because a bug didn’t get reported on time.

Any bugs will undoubtedly frustrate your customers and possibly dissuade them from your product. This is especially true with mobile apps, where users are spoiled for choice.

Here are the numbers to prove it:

As you can see, users seldom have the patience for dealing with bugs and would rather abandon an app than wait for its resolution.

This is why bug reporting is crucial: it helps avoid these unpleasant scenarios.

For example, on May 3rd, 2021, the popular app TikTok suffered a significant glitch—it had reset all of its users’ followers to zero. Every single account displayed the wrong follower count.

Understandably irritated, users took to Twitter to recount their experience and demanded that the app giant resolve the issue as soon as possible. Here’s just one customer’s complaint:

Similar messages flooded TikTok’s Twitter that day, and the hashtag #TikTokDown was soon trending.

You don’t want to cause the same sort of outrage among your customers, which is why it’s essential to stay on top of bugs and report them regularly.

Your users will expect nothing less than perfectly-functioning software.

Bug reporting is what will lead to customer retention. By identifying and clearly describing any errors that occur, a bug report paves the path toward well-performing software solutions.

Yegor Bugayenko, a Director of System Programming Laboratory at Huawei, described a bug reporter’s function best:

Every ticket [bug] is dragging the project from point A, where something is not right, to point B, where it is fixed. Your job, as a ticket [bug] reporter, is to draw that line—clearly and explicitly.

With a well-written bug report, the sooner the issues are corrected, the quicker you can release your software.

How to write a great bug report

Now that we’ve emphasized the importance of quality bug reporting and explained the bug life cycle, there’s one thing left to do—show you how to write a bug report.

There are three main questions the document should answer:

A bug report isn’t helpful unless you’ve addressed the above concerns.

Developers will need to know how the software is behaving as opposed to how it should behave, and the environment in which the bug appears.

Therefore, ensure your team’s reports always contain these three elements—your developers will thank you.

To answer these questions and give developers everything they need, we recommend adopting the following practices.

Create one report per bug

Imagine opening a bug report, and the description reports that certain buttons are unresponsive.

Then the report mentions another button that is responsive, but leads to the wrong page. And, on top of all that, all the buttons are too small.

Most developers would get confused reading such a document. Therefore, it’s advisable to create one report per bug.

Including multiple bugs in one report, however similar the issues are, will likely puzzle and frustrate the developer, impeding their debugging process.

This topic was also discussed in a Quora thread:

According to this developer, the only exception is if the bug reporter is 100% certain that the exact same code has caused multiple bugs.

However, this is quite unlikely, and the reporter would lose time uncovering this information anyway. It’s much easier and faster to simply stick to the one report per bug guideline.

This rule is so essential that Apple has stated they might even reject reports that contain multiple issues:

When a report details multiple bugs, Apple insists it is separated into individual documents. They know that such a convoluted report will only detract from debugging.

Write a detailed description of the bug

A bug report’s primary purpose is to help developers solve errors. To this end, it should be highly detailed to help as much as possible.

For example, the description The login page is not working is not very helpful. The developer will just waste time investigating the issue instead of actually solving the error.

So, what details do developers want to find in a bug report? The graph below depicts all the most essential elements:

At the top should be a title, ideally offering a brief description of the bug.

Following that are the environment specifications (e.g., device type, OS, software version, etc.)

Sometimes the bug only appears after specific actions and can’t be consistently triggered. Reproducibility measures how often the bug appears compared to the number of attempts.

Preconditions detail the prerequisites for a bug to appear, e.g., the WiFi connection.

Steps to reproduce are a massive help for developers, as this information allows them to see the bug themselves.

The expected result vs. the actual result compares how the software currently functions and how it should be functioning.

Finally, the bug’s severity illustrates to what measure the bug affects the software.

Include relevant attachments

Perhaps the easiest method of describing the bug is to present it visually.

This is done by including any relevant attachments such as screenshots, screen recordings, and logs in the bug report.

With an image of the error, the developer sees its impact on the software and can, therefore, better understand the bug.

There are multiple online resources to assist you. For example, Awesome Screenshot is a great tool that enables both screenshots and recordings.

Here’s a preview:

The resource is a two-in-one solution for screenshots and screen recordings, ideal for bug reports.

Logs are also hugely helpful, as they clearly show all the errors that occurred and track a user’s actions. With all this different data, it’s easy to analyze and pinpoint the issue.

For example, here’s a console log:

By examining these logs, developers can dig up the root cause of the bug and uncover where the problem started.

Furthermore, replicating a bug can sometimes be tricky, even when the steps to reproduce it are clearly described.

With a console log, the developer can locate additional information that will help recreate the bug. Such visual attachments are often crucial for correcting the bug.

Use bug reporting software

Although this information might seem a lot to take in, there is software that can streamline the entire process.

With the correct tools, you can essentially automate bug reports and therefore make your developers’ lives much easier.

For example, with Shake, all you need to do is shake your mobile device, and a detailed and thorough bug report will automatically be created and sent to the developers.

Here’s a Shake bug report example:

The report contains screenshots, screen recordings, environment details, logs, steps to reproduce the error, etc.

This is all information the developers will greatly appreciate, and it’s delivered to them effortlessly by simply shaking your device.

If your software is a web application, it’s worth looking into Ybug. Ybug is a website tool which allows end-users to send annotated visual feedback.

However, the software also automatically attaches technical information about the user environment.

You can see the tool in action below:

This resource allows users to submit their feedback, and technical specifications are automatically generated alongside their comments.

Developers will have all the information they need for debugging.

Bug reporting software is a huge advantage, as it significantly accelerates the process and turns manual work into simple automation.

Conclusion

Bug reporting is the process of tracking bugs so as to ultimately remove them from your software.

When bugs are reported, they progress through the bug life cycle from open to closed.

Bug reports should contain one report per bug so as not to confuse the developer. Furthermore, they should provide a detailed bug description and include visual attachments.

However, it’s wise to invest in bug reporting software to automate this entire process.

Apply this newfound knowledge, and your software will soon be bug-free.