Rebuild or Report?

On helping yourself and others through precise Bug Reports


5 min read
Rebuild or Report?

Nowadays, every code project depends on various third party and additional libraries. Truth be told, we wouldn’t be able to create apps or webpages that fast if we would have to build everything from scratch. Typically, we add a library via our favored package manager and give it a go. We start using that specific library, read the docs, figure out how it works and use it for our purposes. Best case, that’s it. Unfortunately, in practice, it may turn out differently.

Make no Mistake, Mistakes happen

While we work with a specific library, we may encounter some roadblocks. Sometimes that’s due to missing or bad documentation. Or it might be due to our missing knowledge about some things. Anyway, sometimes, we eventually realize that it is not us, it was them all along. We found a mistake, a so-called bug.

A (software) bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways.

— Wikipedia

If we’re honest, our first reaction may be that we get angry at the library itself or the author, but, after acknowledging that we never wrote flawless or bug-free code, we look for a solution.

We found a Bug! Now what?

Logically, some of us start to follow the most obvious path. We throw that library away and write a replacement ourselves…not.

Ok, honestly, we may think about that, but it in most cases that is neither the right nor the best way to go. Many authors put a lot of effort into creating software libraries and shared it with us. So, most undoubtedly, a lot of knowledge, work, testing and time has already gone into it.

Therefore, there is a high chance that rewriting that library from scratch is the least favorable option.

So, what should we do?

Worst case scenario: We don’t do anything and leave it be. But this way it won’t get fixed, the authors won’t be aware of it, and others will encounter the same bug and spend unnecessary time on it.

Best case scenario: We track down the bug, propose a solution to the authors and hope they will acknowledge and accept it. But sometimes we don’t have the means, options or time to fix the bug. Consequently, the second best way is telling the authors about the bug you found. But wait, before we file a bug we should ask ourselves the following question

Are we running the latest version of the library?

Writing good Bug Reports helps Yourself and Others

We at img.ly provide a software library for photo editing. Thus, we are both library authors as well as users.

I would like to say that we don’t ever make mistakes, but truth be told, everyone does.

As you can imagine, providing photo editing capabilities results in a lot of code for rendering, UI, or other business logic. Although all the usual quality checks are in place, mistakes or unthought-of use-cases manifest in bugs, no matter what.

Consequently, we get bug reports. Now, unfortunately, an awful lot of said bug reports only contain a single line that literally says:

“XYZ does not work.”

While, this is far better than not reporting it at all, it doesn’t help much in hunting down the bug.

With bug reports like this, we spend a lot of our time on trying to reproduce the bug or asking for details on how to reproduce it. That time would be better spent on improving the libraries or helping other users. However, with just a little help we’d be able to find bugs faster and be more effective. So, what should a proper bug report look like? From our point of view, bug reports should be comprised out of the following things:

  • One bug at a time,
  • the context of the bug,
  • a minimal runnable example, and
  • the steps to reproduce the bug.

One bug at a time

In reality, one may encounter multiple bugs at the same time, and might wish to drop them at the library authors all at once. However, it is far better not to combine multiple problems even if they seem to be alike. So, one should always report each bug individually.

Describing the context

Often forgotten when reporting bugs is to describe the context the bug occurs in. For us, a good bug report contains at least the following specifications:

  • A description,
  • the environment
  • the actual and desired output, and
  • attachments (e.g. Screenshots).

Description

First thing we need to know is what the bug is about. This includes:

  • A short meaningful title of the bug (e.g. Exporting image after crop and rotate corrupts output), and
  • a description of the bug which explains the error in an understandable manner.

Environment

Due to the nature of web and app development, software libraries can be used in many different environments. All of which have their own little differences and quirks. Thus, it is very helpful to include information about the environment, including:

  • the used operating system’s version (e.g. iOS 10.1),
  • the device it is running on (e.g. iPhone 7 32GB),
  • the used browser or runtime environment and its version (e.g. Chrome 65.0.3325.181 (64-Bit) or Node.js 8.11.1 ), and not to forget
  • the name of the library and its version/variant (e.g. pesdk-html5 4.1.3).

Actual Output and Expected Output

Often, an experienced developer can classify the bug on the basis of the resulting error or error output only. Therefore, a useful bug report should provide:

  • the actual output that is is observed, and
  • the desired output that should be generated

Attachments

Additionally, attachments are very helpful to pinpoint the bug. Helpful attachments can be but are not limited to:

  • error output or logs generated by the compiler and build system, console output, and stack trace, and whenever the bug results in something that is visual recognizable, and
  • screenshots showing the issue.

Reproducibility is key

While all aforementioned greatly assists to narrow down the context in which the bug appears there is one thing that helps even more:

Even if it seems trivial to reproduce, a good bug report should come with a minimal runnable example that produces the bug in question and a description of how to trigger it.

Providing a minimal running Example

So, one should strip away everything from the current code that isn’t necessary and keep it simple. The faster we and other library maintainers can track down an error, the sooner it’s going to be fixed.

Also, probably it was already necessary to narrow down the issue so stripping it out into a minimal example is not too much work. If possible, the Gist should be provided via a GitHub repository or any other similar sharing system.

Keep it simple to trigger the Bug and be specific about it

While having a minimal example is already lovely, sometimes it needs a bit more than just code to trigger the bug. Writing down precise instructions on how to trigger it is not always easy but being specific dramatically helps to get to it.

That is why one should summarize the problem in brevity and with utmost precision.

Conclusions

From our point of view these are the most important things one needs to consider when reporting a bug. Most certainly, the requirements change and need to be adapted for different types of software. We’d really like your feedback on this. So, if you have any comments and additions please let us know.


Thanks a lot for reading! If you like, you can subscribe to our Newsletter, so we can keep you posted about our latest Articles and Case Studies.

Related Articles

How to Trim and Crop Video in Swift
6 min read
How to Draw on an Image With JavaScript
7 min read
How To Resize an Image in React
6 min read
How To Resize an Image With JavaScript
4 min read
My digital journey to #nfts
5 min read

We’d love to use cookies

Help us improve our Website
We use cookies to provide you with a user-friendly website and for marketing. By clicking accept you agree to the terms of our privacy policy, and help us improve our web presence.

We’d love to use cookies

Help us improve our Website
We use cookies to provide you with a user-friendly website and for marketing. By clicking accept you agree to the terms of our privacy policy, and help us improve our web presence.
Essential Cookies
..are necessary for you to browse our website and use its features, such as accessing secure areas of the site. These cookies are first-party session cookies, and do not provide any information that would make you identifiable.
Functional Cookies
..allow our website to remember choices you have made in the past, like what language you prefer, or what your user name is so you can log in more easily. Generally speaking, they enable us to provide you with a more convenient experience of our website.
Performance Cookies
..collect information about how you use our website, like which pages you visited and which links you clicked on. These cookies are all aggregated and, therefore, anonymized. None of this information can be used to identify you. It is their sole purpose to improve website functions. This includes cookies from third-party analytics services which are for our exclusive use.
Marketing Cookies
..track your online activity and make you identifiable to us. They help us deliver more relevant content to you and therefore improve your user journey. These cookies can share that information with other organizations or advertisers.

GO TOP