Bug submission guidelines
Posted: Sun Dec 29, 2013 9:48 pm
If you think you found a bug in FreeCAD, you can help greatly by reporting that bug to the FreeCAD developers on the FreeCAD issues tracker at https://github.com/FreeCAD/FreeCAD/issues. Bugs reported here on the forum can be easily overlooked or missed by developers, while on the tracker they are sure to stay in the queue until a developer looks at it.
However, if well-made bug reports can help a lot and make the problem very easy to solve, bad bug reports can do the opposite: They can make the developer spend many unnecessary hours on the problem. Such bad reports are therefore often treated with the lowest possible priority, and you might not see your bug fixed.
So, it is important to follow these guidelines when submitting a bug on the tracker:
1. Make sure you use the latest development version to reproduce the bug. The development branches are usually far from being experimental and they contain all the bugfixes since the last stable version. Your bug may be already fixed. The latest development version can be found on https://github.com/FreeCAD/FreeCAD-Bund ... kly-builds.
2. Make sure that what you found is a bug. The definition of a bug is this: Something that is not working, but for which you are sure that it should be working (for example it worked in the past, or it is advertised on the FreeCAD documentation wiki). Otherwise, it might be simply that what you want is not implemented, or maybe you are doing something wrong.
3. Discuss the problem on the Help forum first! This should be done before creating a ticket in the bugtracker, for several reasons: It may not be a bug after all and you will get advice how to proceed; developer time is precious and a discussion here in the forum will produce far better tickets; the helpers in the forum become aware of the bug; you may be offered a workaround until the bug is fixed.
4. Make sure your bug can be reproduced. This is the most important rule. If the developer cannot reproduce your problem on his machine, he will not be able to fix it. So you must give an exact step-by-step procedure that the developer must follow to see your bug happen. For example:
5. Always include your FreeCAD version information. You can easily copy/paste all the needed information by using the "Copy to clipboard" button in FreeCAD, in menu Help -> About FreeCAD. You can then paste that information in your bug report.1. Open FreeCAD
2. Press the "create new document" button
3. Switch to the Part workbench
4. Press the "Create cube" button
5. FreeCAD crashes
6. Include all possible FreeCAD error messages. When something wrong happens in FreeCAD, error messages are often printed, that can give precious information to the developer about what happened. The two places you should check for such error messages in FreeCAD are the Report window (menu View->Panels->Report view), the python console (menu View->Views->Python console). Make sure to include as much error text as possible.
7. If possible, also check the terminal and the FreeCAD log for error messages. A third possible place to look for error messages is the system terminal, which you can get on Linux and Mac systems by opening a terminal, and launching FreeCAD from it, by typing "freecad" <enter>. A fourth place to look for error messages is the FreeCAD log. To produce such a log, you must either run FreeCAD from a terminal by running "freecad -l" or change the properties of your FreeCAD launch icon, and use "freecad -l" instead of "freecad". After running and closing (or crashing) FreeCAD, you will find a file called freecad.log in your FreeCAD user directory (/home/youruser/.FreeCAD on linux and mac, C:/users/youruser/ApplicationData/FreeCAD on windows).
8. Stay cool and patient. We all know bugs are annoying, but nobody is here to serve you, developers will work on solving bugs when they have time to do so, and efficient bug fixing depends largely on how helpful people submitting bugs are. By following the above rules, you'll be doing a very good job when submitting your bug, and make sure your bug is treated in the best possible manner. Thanks!