This is a text-only version of the following page on https://raymii.org:
---
Title : Filing Effective Bug Reports
Author : Ben Everard
Date : 03-05-2015
URL : https://raymii.org/s/articles/Filing_Effective_Bug_Reports.html
Format : Markdown/HTML
---
This article was originaly published in [Linux Voice, issue 2, May 2014][1].
This issue is now available under a [Creative Commons BY-SA license][2]. In a
nutshell: you can modify and share all content from the magazine (apart from
adverts), even for commercial purposes, providing you credit Linux Voice as the
original source, and retain the same license.
This remix is converted manually to Markdown and HTML for ease of archiving and
copy-pasting.
<p class="ad"> <b>Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below:</b><br><br> <a href="https://leafnode.nl">I'm developing an open source monitoring app called Leaf Node Monitoring, for windows, linux & android. Go check it out!</a><br><br> <a href="https://github.com/sponsors/RaymiiOrg/">Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.</a><br><br> <a href="https://www.digitalocean.com/?refcode=7435ae6b8212">You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $100 credit for 60 days. </a><br><br> </p>
Other converted Linux Voice articles [can be found here][4].
* * *
Found a mistake in your favourite software? Share the knowledge, help the
developers out and we can all help make software better.
### Filing Effective Bug Reports
A bug is an incorrect behaviour in a piece of software. This could be anything
from the program crashing, to not rendering graphics properly to small things
like spelling mistakes in the user interface. They're a fact of life for anyone
who uses computers and no software is completely immune to them. Open source
software will get a lot better if people help the developers by filing good bug
reports, because unless developers know what the problems are, they can't fix
them.
The most important thing with bug reports is to not be afraid of them. Anyone
who's written software knows that bugs are a part of life and they won't be
mortally offended by the suggestion that their software is somehow imperfect. In
fact, they'll probably be grateful for the feedback.
There are a few simple things that can make bug reports much more useful, and
we'll have a look at these here. The first step, though, is to make sure you
have the latest version of the software. You should upgrade through your package
manager. If possible, you should check the latest version on the program's web
page, and install this if it's more recent.
![Bugzilla][5]
> Bugzilla (a bug tracker developed by Mozilla) is one of the most common bug
management tools used in open source projects.
As far as filing bug reports are concerned, there are two types of software:
those with bug trackers and those without. Bug trackers are databases of bug
information, typically with a web front-end. If you notice a bug, the first
stage is to go to the project's website and find out how to report bugs. Larger
projects will usually have a website describing what to do, and any information
in that obviously supersedes any general advice we give here. If there isn't a
bug tracker, you'll need to email either the developer or a mailing list with
information about the problem.
There's no point in flooding bug trackers with duplicate reports, so before you
submit anything, check to see if the problem is already on the system. A bug
tracker should let you search the current reports, while projects without
trackers often have information about known problems in release notes, or
elsewhere on their website.
### Filling a report
Regardless of the bug you've found, there are a few pieces of information that
you absolutely must include for the report to be useful at all. This is the
version of the software you're using, the operating system you're running, and
information about the hardware you're running on. Most of the time, there will
be specific fields in the bug tracker that you need to fill in for this. After
that, there is usually a text box where you can enter a description of the
problem.
The key to a good bug report is reproducibility. If a developer can't reproduce
the bug, they can't investigate it and they certainly can't test if a fix works.
If you come across a bug, the first step is to make sure you know what caused
it. This means shutting down the software, then re-tracing your steps to see if
it happens again. If it does, these are the steps you need to enter into the bug
report. If it doesn't, you need to look a little bit harder to see what
triggered the bug.
Take a look at these two reports:
> "Yo, LibreOffice devs. The software breaks when I try to use a picture. Betta
fix it quick or I'm movin back to MS Office"
And:
> "LibreOffice Writer is crashing when inserting a picture into a document.
Steps to reproduce:
* Open LibreOffice Writer
* Go to File > New > Text Document
* Go to Insert > Image > From File and select image. Note this isn't happening with all images. I've attached an image that is causing a problem
* At this point, the window becomes unresponsive
> This worked fine In LibreOffice 4.1, but has stopped working in LibreOffice
4.2"
(This is only an example, LibreOffice doesn't have a problem with image import.)
The top report is missing loads of key information. What does 'use an image'
mean? What piece of the LibreOffice suite are they using? What image are they
using? Without knowing this, there's simply no way to investigate the problem.
You might look at the bottom one and think that the steps are a bit simplistic.
After all, surely a LibreOffice developer knows how to insert an image without
step-by-step instructions? They probably do, but with most software, there's
more than one way to accomplish a task, so it helps to go through everything in
little steps. Nothing is too basic to be included in a bug report! Also remember
that English may not be the developer's first language, so try to keep it as
clear as possible.
Most bug trackers also enable you to attach files, and these are a great way of
providing the developers with the information they need. In the above example,
we attached an image that caused the problem. As a general rule, you should
include any files that are involved in reproducing the bug (make sure they don't
include any confidential information). Screenshots of the problem happening are
often useful as well, though not always possible if the program is crashing.
![Github][6]
> GitHub (shown here) and most other popular source code management platforms
also have bug trackers for the software they host.
### After the report is filed
What happens after the bug is filed will depend on the project. On smaller
projects, it may go straight to a developer who will look into it. In larger
projects, they will often be triaged by a bugfixing team who will try to
reproduce the bug before assigning it to the right development team.
It's important for you, as the bug submitter, to keep an eye on the bug report
at this stage because they may need more information in order to reproduce the
bug. Depending on the problem, they may also suggest a workaround so that you
can side-step the bug until it's fixed.
If you're unsure about anything in a bug report, most projects have an IRC
(Internet Relay Chat) channel, and this is usually the best place to get answers
to problems like this, though this does vary from project to project.
### Fixing the problem
It's possible that the developer will reject the bug. This could be because the
problem is caused by something other than the software itself (such as incorrect
configuration), or because they don't think it's a problem (for example, you
could be doing something outside of the program's intended use).
Hopefully, though, the bug will be accepted and looked into by the development
team. Usually, they'll release a fix and ask you (the bug submitter) to test it
to see if it works. This obviously won't go straight into your distro's package
manager, so you'll usually need to compile the new source code with this fix in.
After this, you should update the bug with information about whether the fix has
worked or not.
If all goes to plan, the final step is to mark the bug as resolved in the bug
tracker (see the project's documentation for details of how to do this), or
letting the developer know that it's worked.
There is one exception to the bug submission process we've talked about here:
security issues. Most bug trackers are public, so you shouldn't post any
information that could be used to exploit the system, unless the project's
documentation explicitly tells you to. If you find a security issue, look at the
software's website for guidance, or email the developers directly. It is
possible to track security issues with CVEs (Common Vulnerabilities and
Exposures) numbers, but this isn't essential.
Filing a bug report doesn't take long, and you should recoup that time by having
working software once the bug's fixed. Public bug reporting is an essential part
of the free software development cycle. It doesn't matter if you've never
touched a line of code in your life - by helping the developers, you can
contribute to the free software community and we'll all benefit.
### Boxout 1 - Get more involved
If you want to get more involved in testing open source software, most large
open source projects are looking for volunteers to help out. This can include
working on bug hunts before big launches or helping triage and investigate
reported bugs. It's a great way to contribute to a project, and it doesn't
require any programming skill.
LibreOffice is an excellent place to start. The team are incredibly friendly to
new testers, and they have a three-day bug hunting session before each point
release. The last one (before 4.2) was in December, and you can see details
about it on the [project website][7].
Keep an eye on [The Document Foundation's blog][8] for details of upcoming
events. Alternatively, you could start using beta releases of software that's
important to you. These early releases tend to have more bugs in them than final
releases, and they need people like you to find all these problems so they can
be fixed before the final release. What's more, it gives you (as a user) a
chance to make sure that new versions will work properly on your setup with your
data.
[1]: http://www.linuxvoice.com/download-linux-voice-issue-2/
[2]: https://creativecommons.org/licenses/by-sa/3.0/
[3]: https://www.digitalocean.com/?refcode=7435ae6b8212
[4]: https://raymii.org/s/tags/linux-voice.html
[5]: https://raymii.org/s/inc/img/linuxvoice/2/bugs1.png
[6]: https://raymii.org/s/inc/img/linuxvoice/2/bugs2.png
[7]: https://wiki.documentfoundation.org/BugHunting_Session_4.2.0
[8]: http://blog.documentfoundation.org
---
License:
All the text on this website is free as in freedom unless stated otherwise.
This means you can use it in any way you want, you can copy it, change it
the way you like and republish it, as long as you release the (modified)
content under the same license to give others the same freedoms you've got
and place my name and a link to this site with the article as source.
This site uses Google Analytics for statistics and Google Adwords for
advertisements. You are tracked and Google knows everything about you.
Use an adblocker like ublock-origin if you don't want it.
All the code on this website is licensed under the GNU GPL v3 license
unless already licensed under a license which does not allows this form
of licensing or if another license is stated on that page / in that software:
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Just to be clear, the information on this website is for meant for educational
purposes and you use it at your own risk. I do not take responsibility if you
screw something up. Use common sense, do not 'rm -rf /' as root for example.
If you have any questions then do not hesitate to contact me.
See https://raymii.org/s/static/About.html for details.