Categories:


Archives:

How to report a bug

by Yorik on 12.12.2015 in opensource

One of the coolest thing you get when working with open-source software, is the possibility to report bugs to the developers, and follow the progresses until it gets fixed. Most, if not all open-source software has, somewhere, a bug tracker, which is an online application where you open such a bug report (sometimes called "issue" or "ticket"). FreeCAD's bug tracker is at http://www.freecadweb.org/tracker . A developer of the project will then usually look at your report, and then do something with it, that hopefully would be fix the bug, but, depending on your report can also be reject it, in case it is actually not a bug, or ask you for further information in case you didn't explain well enough or didn't do all that was required.

The vast majority of bug reports fall in this last category. If you think that most open-source developers have a limited amount of time to dedicate to the project, wasting that time on having them correct bad bug reports until they can do something with it can do more harm than good to the project.

Also, an open-source project is not a company, and developers are not good Samaritans. Nobody is forced to fix other people's problems. Usually, on a bug tracker, developers pick bugs they are interested in fixing. So you'd better help as much as you can and make a bug report that is clear and easy to handle, in other words, make the developer actually want to fix your bug. Otherwise, it might stay at the bottom of the basket for a very long time with nobody interested in looking at it.

So here go a couple of simple rules to make a nice, clear and attractive bug report:

  1. Be friendly. Remember, nobody is forced to handle your report. You might as well not ditch your chances right from the start... My favorite method, write it just like if you were writing an email (provided you write friendly emails of course

  2. Search the bug tracker to make sure that your bug hasn't already been reported before opening a new one. All trackers have a "search" button.

  3. In order to fix a problem, a developer must be able to reproduce it. This is an absolute rule. If the developer cannot see the problem, he cannot fix it. So explain, as clearly, simply as possible, as if you were explaining to any other person, what to do to see the bug happening, for example: 1) open the application 2) press the button "start a fireworks" 3) expected result: the fireworks starts 4) What happens instead: no fireworks has started. This is a clear description, and the developer can easily verify that the fireworks indeed didn't start.

  4. It is sometimes hard to know if something is a bug or not. Basically a bug is "something that should work, but is not working". Are you sure that it should work the way you think it should? For example, if it did work like that before, then it is clearly a bug. If not, there might be a reason why it doesn't work as you think it should. Or maybe it simply wasn't implemented yet. It might be best to discuss the matter before (see point 6 below).

  5. Give as much information as possible about the environment where the project is running. Many bug trackers will ask for specific items such as your operating system, its version, and the version of the project you are using. Any detail that might help identifying the cause of the problem. In other words, help as much as you can!

  6. All projects also have other ways to discuss with developers and other users: forums, mailing lists, IRC channels, etc. If you are not sure of how to proceed, discuss you issue there first. Others will surely indicate you what to do.

  7. Be prepared to help further. Sometimes a bug affects only you, you might be asked for more information, or to test something. Don't abandon your bug report, help people to get it fixed!

If you do all this, your bug reports will be well received anywhere, and you give them the best chances to be considered an interesting task to take by a developer, and to be fixed quickly.

Finally, as someone reminded me in a comment, it is true that filing bug reports can sometimes be tedious and bureaucratic, and more often than not, you feel discouraged because nobody on the other side seems to give much attention to the problem. I have honestly not much idea to circumvent this, but remember the idea behind the whole thing, which is not as much to fix your particular problem immediately, rather to leave it registered to make sure it won't go forever unnoticed. Every user has his particular way of working, and you will see things that others don't see. At the end, it is the crossing of the different paths of each user that end up traversing the project from end to end in different ways, that allow a project to mature and gain stability. Bug reports are essential to achieve that.

So please bear with the bureaucracy and the laziness of developers, don't place your hopes too high in a quick fix, and submit more bug reports!

by Yorik on 12.12.2015 in opensource