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.
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).
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.
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
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.
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.