Raymii.org

Table of Contents

• Filing Effective Bug Reports
• Filling a report
• After the report is filed
• Fixing the problem
• Boxout 1 - Get more involved

This article was originaly published in Linux Voice, issue 2, May 2014. This issue is now available under a Creative Commons BY-SA license. 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.

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:

I'm developing an open source monitoring app called Leaf Node Monitoring, for windows, linux & android. Go check it out!

Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.

You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $200 credit for 60 days. Spend $25 after your credit expires and I'll get $25!

Other converted Linux Voice articles can be found here.

---

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

Keep an eye on The Document Foundation's blog 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.

Tags: articles , bug , bug-reporting , bugzilla , errors , github , linux-voice , linux-voice-issue-2-2014