125 lines
6 KiB
Text
125 lines
6 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
|
|
<!ENTITY base CDATA "../..">
|
|
<!ENTITY date "$FreeBSD: www/en/gnome/docs/bugging.sgml,v 1.12 2004/01/23 02:47:08 viny Exp $">
|
|
<!ENTITY title "FreeBSD GNOME Project: Reporting a Bug">
|
|
<!ENTITY % gnomeincludes SYSTEM "../includes.sgml"> %gnomeincludes;
|
|
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
|
|
]>
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<h2>1. What to report?</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>There are plenty of examples of totally useless bug reports,
|
|
something like <i>"Hey, gnomefoo port is broken. I'm running
|
|
FreeBSD-X.Y. Please fix."</i> 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:</p>
|
|
|
|
<ul>
|
|
<li><p>Exact version of the operating system (usually output of
|
|
<tt>uname -a</tt>).</p></li>
|
|
<li><p>List of all packages installed on your system.</p></li>
|
|
<li><p>Your environment (output of <tt>/usr/bin/env</tt>).
|
|
<li><p>If you are building from ports then the approximate time
|
|
when you last updated your ports tree.</p></li>
|
|
<li><p>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.</p></li>
|
|
</ul>
|
|
|
|
<p>In addition, try to answer the following questions:</p>
|
|
|
|
<ul>
|
|
<li><b>What exactly is the problem?</b> : Explain the problem as
|
|
clearly and precisely as possible. Try to limit the actual
|
|
problem description to one or two key sentences.</li>
|
|
<li><b>Where is the problem occurring?</b> : 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 <b>LANG</b> environment variable) the problem is
|
|
occurring.</li>
|
|
<li><b>When did the problem first occur?</b> : 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).</li>
|
|
<li><b>What is the magnitude of this problem?</b> : 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.</li>
|
|
</ul>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.
|
|
</p>
|
|
|
|
<h2>2. Where to report?</h2>
|
|
|
|
<p>Before reporting a bug, or even sending an email to the list,
|
|
<a href="http://www.freebsd.org/search/search.html">search</a>
|
|
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.
|
|
</p>
|
|
|
|
<p>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
|
|
<a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
|
|
list</a>, file a problem report in the
|
|
<a href="http://www.freebsd.org/support.html#gnats">FreeBSD bug
|
|
reporting system</a>, send your report to the particular GNOME
|
|
developers via their
|
|
<a href="http://bugzilla.gnome.org/">bug tracking system</a>, or
|
|
any combination of those.<p>
|
|
|
|
<p>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:</p>
|
|
|
|
<ul>
|
|
<li><p>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 <a href="mailto:&email;@FreeBSD.org">
|
|
freebsd-gnome mailing list</a>.</p></li>
|
|
<li><p>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).</p></li>
|
|
<li><p>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.</p></li>
|
|
</ul>
|
|
|
|
&footer;
|
|
</body>
|
|
</html>
|