From 91a631177f951d35f5dc8861f849d4937d2474ae Mon Sep 17 00:00:00 2001 From: Adam Weinberger Date: Mon, 5 Apr 2004 02:14:09 +0000 Subject: [PATCH] Rework some docs to make them useful. And legible. And correct. And stuff. --- en/gnome/docs/bugging.sgml | 149 ++++++++++++++------------------- en/gnome/docs/knownissues.sgml | 25 +++--- en/gnome/docs/volunteer.sgml | 13 +-- en/gnome/index.xsl | 8 +- 4 files changed, 85 insertions(+), 110 deletions(-) diff --git a/en/gnome/docs/bugging.sgml b/en/gnome/docs/bugging.sgml index ee9c361211..aa3c29a266 100644 --- a/en/gnome/docs/bugging.sgml +++ b/en/gnome/docs/bugging.sgml @@ -1,6 +1,6 @@ - + %gnomeincludes; %includes; @@ -9,86 +9,62 @@ &header; -

1. What to report?

+

1. When should I make a bug 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.

+

2. What to report?

-

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:

+

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:

+

  • 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 + portupgrade -a, don't bother sending a bug report + until you've run cvsup and portupgrade.

    • +

  • Information specific for each type of breakage:

    + +
    • + -

    In addition, try to answer the following questions:

    - - - -

    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 +

    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.

    -

    2. Where to report?

    +

    3. 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 +

    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 @@ -99,25 +75,24 @@ 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:

    - &footer; diff --git a/en/gnome/docs/knownissues.sgml b/en/gnome/docs/knownissues.sgml index ba44ffaa2d..fec620f20c 100644 --- a/en/gnome/docs/knownissues.sgml +++ b/en/gnome/docs/knownissues.sgml @@ -1,6 +1,6 @@ - + %gnomeincludes; %includes; @@ -13,23 +13,18 @@ specific to FreeBSD. These are not the only known issues, however. Please familiarize yourself with the GNOME &gnomever; - release notes which contains a - - list of known issues that affect all platforms.

    + release notes.

    + +

    Other release-specific issues can be found in the + general FAQ and the + GNOME &gnomever; upgrade FAQ.

    1. Upgrading from GNOME 2.4 to &gnomever; is tricky

    -

    You should follow the - - instructions for updating to GNOME &gnomever;. This may - still produce errors, however. You may have to re-run - pkgdb -F after each step. If you continue to - encounter errors after following the upgrade instructions, - log the entire upgrade procedure (you can use the -l - option to portupgrade to accomplish this). - Compress and send the log to - &email;@FreeBSD.org. -

    +

    It certainly is tricky, and you are not expected to + accomplish it by hand. Read the + upgrade FAQ for detailed + information.

    2. evolution has a problem with attachments under GNOME &gnomever;

    diff --git a/en/gnome/docs/volunteer.sgml b/en/gnome/docs/volunteer.sgml index a660f56cb3..c01212a1dc 100644 --- a/en/gnome/docs/volunteer.sgml +++ b/en/gnome/docs/volunteer.sgml @@ -1,6 +1,6 @@ - + %gnomeincludes; %includes; @@ -16,7 +16,9 @@

    Send any feedback to diff --git a/en/gnome/index.xsl b/en/gnome/index.xsl index 6910213908..018abbd93f 100644 --- a/en/gnome/index.xsl +++ b/en/gnome/index.xsl @@ -1,4 +1,4 @@ - + - + : A set of office productivity applications. +

    For more information about what GNOME is and isn't, check out + the GNOME Project's + About GNOME page.

    +

    State of the port

    GNOME for FreeBSD is currently supported on 4.9, 5.2,