All software has problems. You may have found what you consider to be the most reliable software ever, but I promise you that buried in there are some problems.

We see this in every-day appliances, such as cars being recalled to have their onboard software updated, as well as the slew of updates and improvements we see in computer, laptop, tablet and mobile phone software.

Why does all software have problems? Because it's written by humans. Software is a complex collection of moving parts, with many of the parts moving at different speeds and with different expectations. Even the best programmers write software with problems, but fortunately the dents in the armour of the programmer's perfection can be resolved due to another feature of software: problems can be fixed.

In computer lingo, these problems are called bugs, and bugs are part and parcel of the software development process. Fortunately, living in the wonderful open source community that we are part of, every one of you can help find and report these bugs and help our programmers to make the software they share even better.

In the open source world, reporting bugs is a hugely important way in which you can contribute to the community. There is a misconception that reporting bugs is considered to be impolite or disrespectful in highlighting defects, or that it simply causes work for the developers. This is definitely not the case.

As a developer on some projects, I can assure you that our users are our eyes and ears for finding bugs and problems in our software. If we don't have the bug reports, we don't know about quality issues.

As such, contributing bug reports is a tremendously valuable exercise, and one that anyone can participate in: it doesn't require a lot of technical experience, or any programming expertise.

In this article, we won't be dwelling on a specific community, so everything here can apply to whatever group you're interested in participating in.

Before we go on, understanding how to report a bug is helped by an appreciation of how software in the Linux community is put together. There are two broad types of community in the Linux world: Upstreams are the independent software projects that create the software you know and love. Examples of these include LibreOffice, OpenShot, Gimp, etc.

Downstreams are the Linux distributions that package and ship the upstream software in an integrated system. Examples include Ubuntu, Fedora and Debian.

The way in which software goes from the programmers' computers to your Linux distribution works a little like this: The upstream programmers create the features in their upstream codebase (eg, producing a feature in OpenShot). The upstream programmers merge all of their features into a central codebase. Interested users in that upstream will test out the features as they appear in the codebase, and test those features and report bugs in them. The programmers then fix those bugs where they see fit.

When the upstream code is ready for release, they take a snapshot of that code and release it with a release number (eg, OpenShot 1.0). With a new upstream release, the distro developers create packages and release them into the development version of their distribution (eg, Ubuntu, Fedora). Interested users of the distribution test the release and report bugs in the distribution's bug tracker.

The anatomy of a bug

The distribution's developers resolve those issues where they see fit and fix them in the distribution (often contributing those fixes back to upstream). When the distribution is ready, it's released with a release number (eg, Ubuntu 12.04).

Here we have two different types of bugs: Bugs that occur in the upstream project. Bugs that could be introduced in the packaging and integration of the software in the downstream distribution. In a perfect world, bugs discovered in a distribution are reported by its users, and if they are found to be bugs that weren't introduced by the distribution's developers, they are reported upstream.

See the Bug linking boxout for more information on how these different bugs can be connected.

Our goal here is to ensure that upstreams know about bugs in which the source is in the upstream software, and that distributions know about bugs that are introduced in the packaging and integration of that software.


Before we can report a bug, we need to know what a bug looks like. In a nutshell, a bug is behaviour in software that is unexpected or inaccurate. Examples of this could include:

You click on a button in a program and the program crashes (this should never happen).

You add two numbers together in a calculator and the wrong result is presented (the calculator should provide accurate results).

A translation is incorrect and shows a culturally incorrect term (the correct definitions should be used for translations).

Each of these examples presumes you know what the correct behaviour should be and you can therefore identify when incorrect behaviour happens. Sometimes, this is more obvious than at others.

You should always remember that bugs are only for unexpected or inaccurate results, not necessarily for design or behaviour decisions that you might not like. For example, if the developers decide to change the icon of an application to a horrible lime green colour, you might hate the look, but it's not a bug. Don't clog up their bug lists with disagreements about direction… this is what other communication channels are for.

All bugs have two important attributes: The symptoms for example, if you click a button in an application and it crashes, the symptoms are pretty stark… you click the button and the application crashes. Other bugs may have more subtle symptoms, such as behaviour gradually degrading, or stability issues occurring.

The cause If you click a button in an application and it crashes, what was the button you clicked on, and did it try to load functionality that contained an issue that caused the crash? Most people who find bugs discover the symptoms first and then dig in to the issue to discover the causes.