os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add `Reporting a Bug' page (still work-in-progress).

Browse source
This commit is contained in:
Maxim Sobolev 2002-01-17 08:09:58 +00:00
parent 042da4eed3
commit d165b4b72d
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=11730
2 changed files with 84 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

3
en/gnome/docs/Makefile
View file

@ -8,6 +8,7 @@
.endif
DOCS= faq.sgml
DOCS+= porting.sgml
DOCS+= porting.sgml
DOCS+= bugging.sgml
.include "${WEB_PREFIX}/share/mk/web.site.mk"

82
en/gnome/docs/bugging.sgml Normal file
View file

@ -0,0 +1,82 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD$">
<!ENTITY title "FreeBSD GNOME Project: Reporting a Bug">
<!ENTITY email 'freebsd-gnome'>
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
]>
<html>
&header;
<h2>Reporting a bug</h2>
<h3>1. What to report?</h3>
<p>The rule of the thumb should be: report as much information as you
can, because even if there is some irrelevant information usually
developers could quite easy filter it out. On contrary, situation is
much worse when there is too little informaton to reliably track down
or reproduce the problem - in this case developers have to speend 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> Nedless to say, that such report is just a waste of
your time, time of the appropriate developer and network bandwidth.
At the bare minimum the report should include the following
information:</p>
<ul>
<li>Exact version of the operating system (usually output of
<tt>uname -a</tt>).</li>
<li>List of all packages installed on your system.</li>
<li>Your environment (output of <tt>/usr/bin/env</tt>).
<li>If you are building from ports then approximate time when you was
last time updating your ports tree.</li>
<li>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 coredump, clean and detailed description
of the problem when application does something unexpected etc. Try
to put yourself into developer's shoes and in each particular case
evaluate what information would be necessary for him to locate the
source of the problem, don't just assume that he alredy knows all
about the problem, but is just too lazy to fix it.</li>
</ul>
<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, even if it is not it could give developer idea about
what to look at and save him some time.</p>
<h3>2. Where to report?</h3>
<p>There are several ways to report a bug in GNOME running on a FreeBSD
system: you could send report to the freebsd-gnome mailing list, file
a problem report in FreeBSD bug reporting system, send your report
to the particular GNOME developers via their bug tracking system 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>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.</li>
<li>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).</li>
<li>If the proble isn't a FreeBSD-specific, but quite serious and you
have a fix available then report both to FreeBSD and authors' bug
tracking system, 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 a next vendor's release.</li>
</ul>
&footer;
</body>
</html>