1. What to report?

The rule of the thumb is: report as much information as you can. Even if there is some irrelevant information developers can easily filter it out. On the contrary, the situation is much worse when there is too little information to reliably track down or reproduce the problem - in this case developers have to spend their time guessing and/or asking originator of report to send more information.

There are plenty of examples of totally useless bug reports, something like "Hey, gnomefoo port is broken. I'm running FreeBSD-X.Y. Please fix." Needless to say, that such a report is just a waste of your time, time of the appropriate developer, and network bandwidth. At a bare minimum the report should include the following information:

• Exact version of the operating system (usually output of uname -a).

• List of all packages installed on your system.

• Your environment (output of /usr/bin/env).

• If you are building from ports then the approximate time when you last updated your ports tree.

• Information specific for each type of breakage: full log of unsuccessful build in the case when the build of the port is broken, stack trace in the case of a core dump, clear and detailed description of the problem when the application does something unexpected, etc. Try to put yourself into the developer's shoes and in each particular case evaluate what information would be necessary for them to locate the source of the problem. Do not just assume that they already know all about the problem, but are just too lazy to fix it.

In addition, try to answer the following questions:

• What exactly is the problem? : Explain the problem as clearly and precisely as possible. Try to limit the actual problem description to one or two key sentences.
• Where is the problem occurring? : Include whether or not you are seeing the problem during compile-time, install-time, or run-time. Also mention what machine (maybe you have multiple) and in what locale (i.e. the value of the LANG environment variable) the problem is occurring.
• When did the problem first occur? : Try to isolate exactly when the problem started to occur. If this never worked, or you always had a problem, say that, too. Also mention when last the problem was observed, as well as when last things were working as expected (if applicable).
• What is the magnitude of this problem? : Explain if the problem is getting worse, getting better, or staying the same. We realize many problems "just are," but this type of information can be helpful in certain cicumstances.

Also, be prepared to answer additional questions. Often times, developers cannot solve or even diagnose a problem right off the bat. So please be understanding when asked to provide more information.

If you have a solution or a workaround for the problem then include it into your report as well, even if you are not quite sure that this is a correct fix. If it is not it could still give the developer an idea about what to look at; and save them some time.

2. Where to report?

Before reporting a bug, or even sending an email to the list, search through the FreeBSD GNOME mailing list archives to see if this has already been reported. Most of the problems reported on the mailing list are repeats, and by searching you can find your solution much faster.

Once you are sure this is a new problem, there are several ways to report a bug in GNOME running on FreeBSD: you could send a report to the freebsd-gnome mailing list, file a problem report in the FreeBSD bug reporting system, send your report to the particular GNOME developers via their bug tracking system, or any combination of those.

It is impossible to define guidelines that will clearly tell you where to report in each particular case - you have to use your own common sense, however some rules follow:

• If the problem is FreeBSD-specific and transient (e.g. checksum mismatch, patch failure, syntax error in port's Makefile etc.) then report to the freebsd-gnome mailing list.

• If the problem is clearly not FreeBSD-specific and you have no readily available solution then report to the developers of the software directly (for most core GNOME components this means that you need to use their Bugzilla bug tracking system).

• If the problem is not FreeBSD-specific, but quite serious and you have a fix available then report both to FreeBSD and author's bug tracking systems, so that the appropriate port will be patched and other users of FreeBSD will be able to benefit from your fix, without the need to wait for the vendor's next release.