Michael Tremer

How to write a good bug report?
by Michael Tremer, May 8, 2013

From our popular series “How to write a good anything”, we just have learned how to write a good commit message, which was a good read for the developers. Now, we are going to learn how to write a good bug report.

This is not only interesting for developers, but also for the users. The developers of an Open Source project rely on bug reports. If the bug reports are missing important information, it takes a lot of effort to get this information. To avoid this problem in the first place, it is important to know what information is actually needed.

Bugs. Every software has got lots of them. Even ours. That’s not a problem, because software is written by humans and humans make mistakes. You cannot completely avoid them, but you can fix them – and for that, we need to identify them!

The IPFire project uses a bug tracking software called Bugzilla. Everyone can sign in and create bug reports. The only thing to keep in mind when doing that are some rules, I am going to explain now:

When to send a bug report?

Always and as quickly as possible. When ever you are certain, that you found a bug, head over to the bugtracker. Even if the bug cannot be fixed right away, it is a great help for other users to find someone else experiencing the same problem.

How to identify a bug?

A bug can be nearly anything, but make sure that you don’t use a feature not as it was intended to be used.

It’s definitely a bug when a program does not behave as expected, crashes, freezes, becomes unresponsive or slow. If you have to work around some problem in order to get something else to work, it’s a bug.

What should a bug report include?

It’s very hard to write a bug report, when you don’t have a clue what the problem is actually about. Often, you’ll need the help of someone who is an expert with the specific software component you are having trouble with. So to make it easy – or even possible – for an other person to understand the issue, provide context. Lots of context. There cannot be enough of it.

Good bug reports help the community to fix problems they found. They help developers getting their work done more quickly and pleasantly. All of this results in a huge improvement of the development workflow and therefore improves the IPFire software. We would be happy if you keep those rules above in mind when sending bug reports.

The IPFire bugtracker is to be found at: http://bugzilla.ipfire.org!

In case you are more interested in this topic and want to read more, please go to Simon Tatham’s page, where he explains all this in a much more verbose manner.

Posted: May 8, 2013 • 1654 views