How to report a bug properly
This post is also available in: Spanish
The first thing to keep in mind when reporting a bug is make sure your software is updated with the last version available, because some times, what you think is a new bug it’s really a problem solved long time ago.
Programmers are weird, we all know, but they are humans too, and consequently, they have an intellect at least equal or higher that the rest of us. This doesn’t mean that they are always right, but we have to trust on their basic notions of intelligence and common sense. When the software doesn’t work at all or is completely broken, you should assume that developers have realized before you did, because they and not you, work daily with it. So, if the software does not work at all, they will be driving crazy to find the best and quickest solution, and probably he will ignore your reports because he can’t afford to miss a second until the software is running again as it should.
In case they have not yet realized that the software is failing more than it should, they will be eternally grateful, and will depend on your help to start solving the problem as up. The perfect thing would be that you could explain face to face the programmer what is going wrong and how you found out, but that’s not possible. What a good bug reporter is supposed to do is to make the programmer run their own copy of the program, follow exactly the same steps you took and force it to fail in the same place you did. And for that, you have to send him all the information you have, send screenshots, videos and anything you can imagine that can help them to face the problem and deal with it.
When we talk about bugs, less is NOT more, so, send all the information and resources you have. If the program reads from a file send a copy of the file. If the program contacts with other computer over a network you can’t probably send a copy of the computer, but if you can, tell them what kind of computer is it and what sofware is running on it. Any information provided will be very useful for them.
Sometimes happens that, after sending a long list of entries and actions, the developer executes its own copy of the program and everything works, nothing goes wrong. Probably you haven’t sent all the information they need. Or maybe, the bug doesn’t show on all computers. Or maybe you have misunderstood what the program is supposed to do, and looking at the same screen, which you thing is wrong they know is right. So, before you get to this point, tell them exactly what happens, describe everything you saw. Tell them why you think what you saw is wrong, or even better, tell them what you expected to see.
If you see error messages don’t hesitate to describe them accurately and with all kind of details, this is very important. By the time, the programmer is not trying to fix the bug, he is just trying to find it, and often this task is more difficult.
The way you express when reporting a bug is also very important. Keep in mind that the mission of a programmer is not decipher hieroglyphics or do sudokus, so, try to express the more “wordly and eloquent” form possible, so he can understand you perfectly without breaking his head.
The first problem of the bug reports is language. Normally, programmers receive bug reports in English from almost every country in the world, most of them non-English speaking countries, but precisely these are the ones that best express, maybe because they make big efforts to make their reports easy to understand. But in the other hand, we also have reports coming from English-speaking people, and these are the most confusing and difficult to understand for the developers, whose english level is not as good as the bug reporters think.
In the following lines we describe some keys to facilitate the programmer’s understanding when reporting a bug:
. Be as specific as possible: There are many things that can be done in different ways. If this is the case, please, explain accurately what is the way you used to find the error. Do not abbreviate or leave without describing steps, although you seem obvious. Programmers have their heads full of data and birds, and when they try to replicate an error maybe they not fall into something that you give of course.
. Be as verbose as you can: Don’t hesitate in sending reports full of details thinking that could be too long or heavy. The programmer will ignore all the useless information, but he will thank your effort to collect all these information. If the report you send is very short, the programmer will have to contact you to collect all the information he needs, and this will made the process unnecessarily lengthen..
. Be careful with the way you express: Pay attention when describing the references. Don’t use generic terms such as “a window”, or “I clicked there and it broke” or “I hit the button” . Instead of that describe what window were, where you clicked exactly and what went broke or which button you clicked. Don’t be afraif to be pedantic or repetitive, because otherwise, the programmer will never understand what you mean, and you both will be wasting your precious time.
. Review before sending: It can be silly but is more important that it seems. Sometimes we don’t realize how unclear we are until we read in detail what we have written. Read it once, twice or even three times if necessary. What really matters is that the time you have invested in writing the report count for something, and if the report is not sufficiently clear is not going to help the programmer to fix the problem.
These are the channels through which you can report a bug to the developers of Pandora FMS:
1. Through Github: This option is primarily intended for developers who are familiar with this platform: https://github.com/pandorafms/pandorafms/issues
2. Through a Web interface: We have an internal bug tracker as in Pandora FMS we use some agile development methodologies, so, any user can report us a bug. Is a extremely simplified interface that allows anyone to contact us even if you have no idea of development.: http://pandorafms.com/Community/report_anything/
3. Via e-mail: Some still prefer to contact us via our mailing list but it is a method almost obsolete.
4. Through the Pandora FMS forum: This is the way chosen by the most part of the users to send us bugs or suggestions. : http://forums.pandorafms.com
5. Through Integria IMS: Our clients with support have access to our ticketing tool, where we attend them under a strict SLA, that includes minimal response times, maximum time solving critical problems, etc. http://integriaims.com
After reading this tips you are probably ready to report a bug. You only need to choose the channel that you find most convenient to let us know, and wait to see how your little big contribution pays off.