How to write a bug report

Posted by Mara Lampert, on 3 April 2024

Imagine you try out a software tool for the analysis of your data and for some reason it is not working in the way you expected. Neither the user documentation, nor forums like image.sc or stack overflow can provide answers. Then it is likely that you either found a bug in the software tool or that a feature you need for your specific use case is not implemented yet.

Communicating this bug/ feature request to the developers is very important. On the short term it might seem easier to just give up on the idea on using this specific tool and moving on to another one to analyse your data. But it helps yourself, future users and the software developers if you report the tools behaviour on your data.

This may sound scary if you never wrote a bug report or feature request before. Therefore, this blog post is meant to help you writing a good report.

Is this a bug or a feature?

Generally, a bug is an error in a system that produces unintended or incorrect results. A feature is an enhancement of the system by adding new functionality. It requires an addition to the source code (which could potentially cause a bug, so they are connected).

In both cases, you want to use an application but it is not working in the expected way. So why do we need to distinguish bug and feature? Because for the developers it is very helpful to know if you report a bug or a feature for the prioritisation within the software development process.

Different types of reports

Bug report: To report a bug helps to identify and fix problems in existing software. The goal of a bug report is to improve the software’s quality and reliability.

Feature request: A feature request focuses on new improvements to enhance the software’s capabilities. The goal of a feature request is to communicate user applications and preferences to the software developers. This helps guiding future development efforts.

Documentation Issue: A documentation issue reports mistakes in the official documentation of a software tool, for example broken links, missing images or unclear / missing instructions.

Depending on the repository, there can also be more options for report types you can choose from (like questions, support requests …).

Github as a platform to write a report

This blog post will focus on how to file reports on Github which is a platform allowing developers to store and manage their code as well as cooperate with others. Hereby, projects are kept on GitHub in so-called repositories.

Finding a repository on GitHub

You can use GitHubs search bar to find a repository and search with a slash at the front for a particular repository and select Search all of GitHub:

Then you can select the repository of your interest. For demonstration purposes, I chose napari-laptrack:

Creating an Issue in a Repository

Within the repository, we navigate to Issues:

Next, we look at other Issues to check if what we want to say already exists, hereby we can look at Open and Closed Issues:

Depending if the Issue does already, partly or does not exist, we proceed after the following scheme:

If the answer is partly or no, we need to create a new issue.

Creating a new Issue

For filing an Issue. you need to sign up for GitHub. If you have done that, press the green New Issue button:

Now I will demonstrate on an example how to file an Issue. This Issue is just for demonstration purposes and is modified from an already existing Closed Issue. It should be noted that this Issue was actually not a bug, but just originated from me wrongly using the tool.

As a title, we choose a concise sentence or bullet point that sums up the problem:

In the report, we want to provide all needed information to understand and reproduce the behaviour. Therefore, we follow the Show, Don’t Tell – Principle. This means we want to make use of screenshots etc. to help clarifying what happened. It is always good to provide a minimum working example to explain the problem. If needed, you can also provide error message or sketches to help others understand your problem. If you show data, check the licensing.

Here is one possible template how to schedule the report:

1.) Subject of the Issue (What part of the tool is the issue relating to? What was your goal when using the tool? Which properties does your data have (e.g. image dimensions))

2.) Package Versions

3.) Steps to reproduce the behaviour (with working demo)

4.) Expected Behaviour

5.) Actual Behaviour (e.g. using screenshots, error messages, ….).

If possible, you can also provide a little pitch/ motivation why this change is important for your research. If you are finished, hit the Submit new issue button.

Note: Developers sometimes provide an Issue template which lists how to file an Issue. If such a template is provided, it is a big help for you, so stick to it (see also awesome-github-templates).

Take home messages

Writing bug reports and feature requests is an important skill and does help you, the developers and the whole community by bridging development and usage

Bug and feature are sometimes hard to distinguish, but it helps the development process if you try to.

There are different types of reports, even beyond bug reports and feature requests

GitHub is a software development platform which can be used to file reports

How to communicate your Issue depends on if it already exists, partly exists or does not exist

search in the user documentation of the corresponding plugin if there is a template for filing an Issue.

Feedback welcome

As I am not a software developer myself, some of you may have input about this blog post and this feedback is heartly welcome. Please comment below, thank you!

Acknowledgements

I want to thank Dr. Robert Haase for his input regarding this blog post.

The author acknowledges the financial support by the Federal Ministry of Education and Research of Germany and by Sächsische Staatsministerium für Wissenschaft, Kultur und Tourismus in the programme Center of Excellence for AI-research „Center for Scalable Data Analytics and Artificial Intelligence Dresden/Leipzig“, project identification number: ScaDS.AI.