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.
- In which component/package did you find the issue? Try to figure out what software is the cause of trouble.
- Exactly explain what you did to trigger the issue. Give much detail and don’t leave out anything that could be important. It often is the little things.
- Explain what you expected and what you got instead.
- Write clear sentences. Read what you have written to make sure that one can understand your text. Keep in mind, that the reader may not have enough context to understand everything. Provide that context.
- Do not guess! Nothing is worse than following a wrong trail. That wastes time and does not solve the problem. Make sure that you point out speculations if you have any. It’s not a bad idea to explain what you think the problem is, but don’t mix it up with the facts.
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.