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

Rework some docs to make them useful. And legible. And correct. And stuff.

Browse source
This commit is contained in:
Adam Weinberger 2004-04-05 02:14:09 +00:00
parent ae273b4b2d
commit 91a631177f
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=20506
4 changed files with 85 additions and 110 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
en/gnome/docs/bugging.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/bugging.sgml,v 1.13 2004/01/24 07:58:44 marcus Exp $">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/bugging.sgml,v 1.14 2004/04/04 21:49:39 phantom Exp $">
<!ENTITY title "FreeBSD GNOME Project: Reporting a Bug">
<!ENTITY % gnomeincludes SYSTEM "../includes.sgml"> %gnomeincludes;
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
@ -9,86 +9,62 @@
<html>
&header;
<h2>1. What to report?</h2>
<h2>1. When should I make a bug report?</h2>
<ul>
<li><b><i>After</i></b> running <tt>cvsup</tt> to obtain the most
recent ports tree.
<li><b><i>After</i></b> running <tt>portupgrade&nbsp;-a</tt> to ensure
that all applications are up-to-date.
<li><b><i>After</i></b> searching through the FreeBSD GNOME
<a href="http://www.FreeBSD.org/search/search.html">Mailing
list archives</a> to see if the problem has already been
reported.
<li><b><i>After</i></b> deciding whether the problem is FreeBSD-specific,
or is a bug in an application that would affect all users,
on all operating systems.
</ul>
<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>
<h2>2. What to report?</h2>
<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>
<p>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.</p>
<p>A good bug report should at least 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>List of all packages installed on your system (output of
<tt>pkg_info</tt>).</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>
<li><p>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 haven't run
<tt>portupgrade&nbsp;-a</tt>, don't bother sending a bug report
until you've run <tt>cvsup</tt> and <tt>portupgrade</tt>.</p></li>
<li><p>Information specific for each type of breakage:</p>
<ul>
<li>If a port will not build, provide a full log of the
unsuccessful build.
<li>If a program produces a core dump, provide a stack trace.
<li>If an application produces unexpected behaviour, provide
a clear and detailed description.
</ul>
</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
<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.
it is a proper fix. Even if the fix isn't quite right, it could still
point others in the right direction.
</p>
<h2>2. Where to report?</h2>
<h2>3. 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
<p>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
<a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
@ -99,25 +75,24 @@
<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>
<li><p>If the problem is FreeBSD-specific (usually, this means
a problem with building or upgrading), then report to the
<a href="mailto:&email;@FreeBSD.org">freebsd-gnome mailing
list</a>, or file a bug report through the
<a href="http://www.FreeBSD.org/support.html#gnats">FreeBSD bug
reporting system</a>.</p></li>
<li><p>If the problem has to do with an application's
behaviour, report the problem directly to the applicaiton's
developers through the GNOME project's
<a href="http://bugzilla.gnome.org/">bug tracking system</a></p></li>
<li><p>If the problem is quite serious, not necessarily
FreeBSD-specific, <i>and</i> 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 to CVS, and the FreeBSD GNOME team can apply the
patch immediately to the ports tree without needing to wait
for the next release.</p></li>
</ul>
&footer;

25
en/gnome/docs/knownissues.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/knownissues.sgml,v 1.10 2004/01/24 07:58:44 marcus Exp $">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/knownissues.sgml,v 1.12 2004/04/04 22:07:06 adamw Exp $">
<!ENTITY title "FreeBSD GNOME Project: Known Issues with GNOME &gnomever; on FreeBSD">
<!ENTITY % gnomeincludes SYSTEM "../includes.sgml"> %gnomeincludes;
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
@ -13,23 +13,18 @@
specific to FreeBSD. These are not the only known issues,
however. Please familiarize yourself with the GNOME &gnomever;
<a href="http://www.gnome.org/start/&gnomever;/notes/">
release notes</a> which contains a
<a href="http://www.gnome.org/start/&gnomever;/notes/rnknownissues.html">
list</a> of known issues that affect all platforms.</p>
release notes</a>.</p>
<p>Other release-specific issues can be found in the
<a href="faq2.html">general FAQ</a> and the
<a href="faq26.html">GNOME &gnomever; upgrade FAQ</a>.</p>
<h3>1. Upgrading from GNOME 2.4 to &gnomever; is tricky</h3>
<p> You should follow the
<a href="http://www.FreeBSD.org/gnome/docs/faq2.html#q5">
instructions</a> for updating to GNOME &gnomever;. This may
still produce errors, however. You may have to re-run
<tt>pkgdb -F</tt> after each step. If you continue to
encounter errors after following the upgrade instructions,
log the entire upgrade procedure (you can use the <tt>-l</tt>
option to <tt>portupgrade</tt> to accomplish this).
<b>Compress</b> and send the log to
<a href="mailto:&email;@FreeBSD.org">&email;@FreeBSD.org</a>.
</p>
<p>It certainly is tricky, and you are not expected to
accomplish it by hand. Read the
<a href="faq26.html">upgrade FAQ</a> for detailed
information.</p>
<h3>2. evolution has a problem with attachments under GNOME &gnomever;</h3>

13
en/gnome/docs/volunteer.sgml
View file

@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY base CDATA "../..">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/volunteer.sgml,v 1.8 2004/01/24 07:58:44 marcus Exp $">
<!ENTITY date "$FreeBSD: www/en/gnome/docs/volunteer.sgml,v 1.9 2004/04/04 21:49:39 phantom Exp $">
<!ENTITY title "FreeBSD GNOME Project: How To Help">
<!ENTITY % gnomeincludes SYSTEM "../includes.sgml"> %gnomeincludes;
<!ENTITY % includes SYSTEM "../../includes.sgml"> %includes;
@ -16,7 +16,9 @@
<ul>
<li>
<p>Test existing <a href="../../ports/gnome.html">ports</a>, and
<a href="bugging.html">report bugs</a>.</p></li>
<a href="bugging.html">report bugs</a>. Try to build with
weird configurations intentionally, before someone else tries
to do so cluelessly.</p></li>
<li>
<p>Regularly install GNOME from packages, and report any problems
with the install or the functionality.</p></li>
@ -27,13 +29,12 @@
<p><a href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-SUBSCRIBE">
Subscribe</a> to the freebsd-gnome mailing list, and help
answer users' questions.</p></li>
<li>
<p>Take patches and feedback from GNOME-related FreeBSD PRs
back to GNOME authors so that the patches can be integrated
into the next release of the application.</p></li>
<li>
<p>Proofread the FreeBSD GNOME <a href="../">project pages</a>,
and offer feedback and updates.</p></li>
<li>
<p>If you are brave, please help fix the <tt>lang/mono</tt> port!
</p></li>
</ul>
<p>Send any feedback to <a href="mailto:&email;@FreeBSD.org">

8
en/gnome/index.xsl
View file

@ -1,4 +1,4 @@
<!-- $FreeBSD: www/en/gnome/index.xsl,v 1.47 2004/02/16 22:39:49 adamw Exp $ -->
<!-- $FreeBSD: www/en/gnome/index.xsl,v 1.48 2004/04/04 22:07:06 adamw Exp $ -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
@ -9,7 +9,7 @@
<xsl:import href="includes.xsl"/>
<xsl:variable name="base" select="'..'"/>
<xsl:variable name="date" select="'$FreeBSD: www/en/gnome/index.xsl,v 1.47 2004/02/16 22:39:49 adamw Exp $'"/>
<xsl:variable name="date" select="'$FreeBSD: www/en/gnome/index.xsl,v 1.48 2004/04/04 22:07:06 adamw Exp $'"/>
<xsl:variable name="title" select="'FreeBSD GNOME Project'"/>
<xsl:output type="html" encoding="iso-8859-1"
@ -119,6 +119,10 @@
Office</a>: A set of office productivity applications.</li>
</ul>
<p>For more information about what GNOME is and isn't, check out
the GNOME Project's
<a href="http://www.gnome.org/about/">About GNOME page</a>.</p>
<h2><font color="#990000">State of the port</font></h2>
<p>GNOME for FreeBSD is currently supported on 4.9, 5.2,