Bug submission guidelines

Post here for help on using FreeCAD's graphical user interface (GUI).
Forum rules
and Helpful information
IMPORTANT: Please click here and read this first, before asking for help

Also, be nice to others! Read the FreeCAD code of conduct!
User avatar
yorik
Founder
Posts: 13630
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Bug submission guidelines

Post by yorik »

Image

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:
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
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.

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!
Last edited by jmaustpc on Tue Oct 27, 2020 9:43 am, edited 1 time in total.
User avatar
yorik
Founder
Posts: 13630
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Bug submission guidelines

Post by yorik »

I now added a text on top of the bug submit page on the mantis tracker, that links here.
User avatar
Freakinbob
Posts: 5
Joined: Thu Jul 23, 2015 3:14 pm

Re: Bug submission guidelines

Post by Freakinbob »

In the Help FreeCAD section of the documentation wicki it reads:

Report bugs and ask for interesting features
The place to report bugs and suggest new features is the FreeCAD Tracker

Not only would it not let me create an account, because it did not ask me to create a password which logon requires, nor did it send me a confirmation email at all with or without an auto generated password. I tried to log on anonymously, but it did not indicate weather I was logged on or not, and there was no place to report a bug nor make suggestions. :(

Here you explain what a bug is, and what is not, but neither here nor there did I see anything about feature requests. :? Anyhow since I want to suggest some features and make a few suggestions, may I start with this ;) : :idea: Fix the above mentioned issues, and be more clear on where to do what. It would also make sense to have a separate feature request topic area on the forums all together, as well as separating usage "How to's, tips and tricks" from "How to get stuff to work, when it does not work right or as expected".
jmaustpc
Veteran
Posts: 11207
Joined: Tue Jul 26, 2011 6:28 am
Location: Australia

Re: Bug submission guidelines

Post by jmaustpc »

Freakinbob wrote:In the Help FreeCAD section of the documentation wicki it reads:
For future reference if someone finds an error or something that needs updating in the wiki,....please provide the URL so that we can just click on it and be sure that we have gone to the correct part of the wiki. The section of the wiki referred to in the above post had been correct once but was just way out of date.

I have updated the wiki now.

Bugs should be posted and discussed in the Help forum first and if confirmed then a good quality ticket with all the information can be created in the bug tracker.

Feature requests should be discussed in the Open discussion forum.
jon_bondy
Posts: 9
Joined: Sat Jul 30, 2016 12:06 pm

Re: Bug submission guidelines

Post by jon_bondy »

For Windows users, Yorik's post says that the FreeCAD log file may be found here: C:/users/youruser/ApplicationData/FreeCAD

I found the log here on Windows 10: C:/users/youruser/AppData/Roaming/FreeCAD

Jon
EGlaz
Posts: 1
Joined: Wed Feb 01, 2017 11:03 am

Re: Bug submission guidelines

Post by EGlaz »

Hello!
I want post a bug, but i can not register in bug tracker because "visual captcha" doesn't show anything! I have tried Win & Linux with Firefox, IE, Chromium - all the same.
Visoble captcha.png
Visoble captcha.png (25.86 KiB) Viewed 646972 times
User avatar
yorik
Founder
Posts: 13630
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Bug submission guidelines

Post by yorik »

EGlaz wrote:"visual captcha" doesn't show anything
There is indeed a problem with the mantis catchpa, but I couldn't find what's wrong... Anyway, we'll upgrade the mantis software to the new 2.0 version ASAP, hopefully that error will be gone then.
User avatar
Kunda1
Veteran
Posts: 13434
Joined: Thu Jan 05, 2017 9:03 pm

Re: Bug submission guidelines

Post by Kunda1 »

Yorik, I propose the following change to the Guidelines. I've just increased the font size of each step. (I can delete this post after this discussion is over)
yorik wrote: Sun Dec 29, 2013 9:48 pm Image

If you think you found a bug in FreeCAD, you can help greatly by reporting that bug to the FreeCAD developers on the FreeCAD bug tracker at http://www.freecadweb.org/tracker/. 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 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.

2. If you are unsure, discuss the problem on the forum first. Open a new topic here on the forum, in the help section, and ask if what you found is a bug. Other users will surely be able to help you determining what you should do.

3. 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:
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
4. 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.

5. 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->Views->Report view), the python console (menu View->Views->Python console). Make sure to include as much error text as possible.

6. 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).

7. 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!
Alone you go faster. Together we go farther
Please mark thread [Solved]
Want to contribute back to FC? Checkout:
'good first issues' | Open TODOs and FIXMEs | How to Help FreeCAD | How to report Bugs
chrisb
Veteran
Posts: 53785
Joined: Tue Mar 17, 2015 9:14 am

Re: Bug submission guidelines

Post by chrisb »

Since I've seen how easy the very big banner in the bug tracker is ignored, I'm afraid we cannot expect much from increasing the font, but we can give it a try. Perhaps it doesn't have to be that big. But there is something more important:

We require a forum discussion before opening a ticket. So point two should read

2. Discuss the problem on the forum first!
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
User avatar
Kunda1
Veteran
Posts: 13434
Joined: Thu Jan 05, 2017 9:03 pm

Re: Bug submission guidelines

Post by Kunda1 »

chrisb wrote: Tue Oct 02, 2018 9:59 pm Since I've seen how easy the very big banner in the bug tracker is ignored, I'm afraid we cannot expect much from increasing the font, but we can give it a try. Perhaps it doesn't have to be that big. But there is something more important:

We require a forum discussion before opening a ticket. So point two should read

2. Discuss the problem on the forum first!
Yea, I agree with tweaking #2
and I still think bolded text is a good way to go.
Alone you go faster. Together we go farther
Please mark thread [Solved]
Want to contribute back to FC? Checkout:
'good first issues' | Open TODOs and FIXMEs | How to Help FreeCAD | How to report Bugs
Post Reply