FreeBSD GNOME Project: Reporting a Bug
1. When should I make a bug report?
- After running any build failure output through gnomelogalyzer.sh.
- After running portsnap to obtain the most recent ports tree.
- After running portupgrade -a or portmaster -a to ensure that all applications are up-to-date. Do not forget to read in /usr/ports/UPDATING first before you upgrade those installed ports.
- After searching through the FreeBSD GNOME Mailing list archives to see if the problem has already been reported.
- After deciding whether the problem is FreeBSD-specific, or is a bug in an application that would affect all users, on all operating systems. If you cannot determine if the problem is FreeBSD-specific or not, then send your problem to the freebsd-gnome mailing list, and we can help decide where the problem lies.
2. What to report?
Always report as much information as you can. Too much information is always preferable to too little information. Superfluous information can be filtered out; developers like to play guessing games with code, not with bug reports.
A good bug report should at least include the following information:
Exact version of the operating system (usually output of uname -a).
List of all packages installed on your system (output of pkg_info).
Your environment (output of /usr/bin/env).
If you are building from ports, note approximately how long it has been since you last updated your ports tree. If it has been more than a day, or if you have not run portupgrade -a or portmaster -a, do not bother sending a bug report until you have run portsnap and portupgrade/portmaster.
Information specific for each type of breakage:
- If a port will not build, provide a full log of the unsuccessful build by either uploading it to any website, copy-and-paste to http://freebsd-gnome.pastebin.com, or send-pr(1) with attachment. Try to avoid sending any attachments to the mailing list, because attachments sent to FreeBSD mailing lists are usually discarded by the mailing list software.
- If a program produces a core dump, provide a back trace. Back traces are only useful if the application (and possibly its dependencies) are compiled with debugging symbols. See these instructions for more information on obtaining useful back traces. In general, though, you can build and install your port with the following command to produce binaries that will have useful debugging symbols: make WITH_DEBUG="yes" install
- If an application produces unexpected behavior, provide a clear and detailed description, including a description of the behavior that you were expecting.
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 it is a proper fix. Even if the fix is not quite right, it could still point others in the right direction.
3. Where to report?
Once you are sure it 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 application's developers via the GNOME bug tracking system, or any combination of those.
If the problem is FreeBSD-specific (usually, this means a problem with building or upgrading), then report to the freebsd-gnome mailing list, or file a bug report through the FreeBSD bug reporting system.
If the problem has to do with an application's behavior, report the problem directly to the application's developers through the GNOME project's bug tracking system
If the problem is quite serious, not necessarily FreeBSD-specific, and you have a fix available, report it to both the FreeBSD GNOME team and the application's developers. This way, the application's developers can apply the patch upstream, and the FreeBSD GNOME team can apply the patch immediately to the ports tree without needing to wait for the next release.