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

Major additions of text to this article:

Browse source 
- continue to add more information that is specific to the web-based
   form as opposed to send-pr(1).  In particular, mention problems that
   are particular to that method.

 - greatly expand the text sections about various fields such as
   'categories' to try to adddress continuing misunderstanding on
   the part of our users.

 - discuss the fact that spammers will most likely find your email
   address from a GNATS submission.

 - demote kernel panics to 'serious' to represent commonly accepted
   usage.  Reserve 'critical' for data corruption issues or things that
   would be considered 'showstoppers' for an upcoming release.  (I am
   using my bugmeister hat for this change.)

 - reiterate that serious security problems should go to secteam, not
   into GNATS.

 - document the common problems seen when submitting PRs, including
   our anti-spam measures and the 'lost PR' index problem.

 - deprecate the use of HTML-only messages.  Regression testing using
   the spam filters shows that close to 100% of such messages are spam.
   (The filters have been tuned to correctly pass HTML that is included
   in patches but reject HTML that conforms to all the common abuse
   patterns.  I am using my bugmeister hat for this change).
This commit is contained in:
Mark Linimon 2005-10-22 07:03:20 +00:00
parent 250212cee2
commit c9a087a388
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=26110
1 changed files with 157 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

175
en_US.ISO8859-1/articles/problem-reports/article.sgml
View file

@ -527,6 +527,8 @@
<section>
<title>Attaching patches or files</title>
<para>The following applies to submitting PRs via email:</para>
<para>The &man.send-pr.1; program has provisions for attaching
files to a problem report. You can attach as many files as
you want provided that each has a unique base name (i.e. the
@ -586,6 +588,8 @@
<section>
<title>Filling out the template</title>
<para>The next section applies to the email method only:</para>
<para>When you run &man.send-pr.1;, you are presented with a
template. The template consists of a list of fields, some of
which are pre-filled, and some of which have comments explaining
@ -604,7 +608,8 @@
adding one or more email addresses to the
<literal>Cc:</literal> header.</para>
<para>Next comes a series of single-line fields:</para>
<para>In the email template you will find the following two
single-line fields:</para>
<itemizedlist>
<listitem>
@ -621,12 +626,31 @@
<application>CVSup</application>.</para>
</listitem>
</itemizedlist>
<para>The next section describes fields that are common to both
the email interface and the web interface:</para>
<itemizedlist>
<listitem>
<para><emphasis>Originator:</emphasis> This is normally
<para><emphasis>Originator:</emphasis>
Please specify your real name, optionally followed
by your email address in angle brackets.
In the email interface, this is normally
prefilled with the <literal>gecos</literal> field of the
currently logged-in
user. Please specify your real name, optionally followed
by your email address in angle brackets.</para>
user.</para>
<note>
<para>The email address you use will become public information
and may become available to spammers. You should either
have spam handling procedures in place, or use a temporary
email account. However, please note that if you do not
use a valid email account at all, we will not be able to
ask you questions about your PR.</para>
</note>
</listitem>
<listitem>
@ -645,7 +669,8 @@
<para>As noted above, if your problem report includes a patch,
please have the synopsis start with <literal>[patch]</literal>;
if you are a maintainer, you may consider adding
if this is a ports PR and you are the
maintainer, you may consider adding
<literal>[maintainer update]</literal> and set the
<quote>Class</quote> of your PR to
<literal>maintainer-update</literal>.</para>
@ -657,15 +682,24 @@
<literal>serious</literal> or
<literal>critical</literal>. Do not overreact; refrain
from labeling your problem <literal>critical</literal>
unless it really is (e.g. <username>root</username> exploit, easily
reproducible panic) or <literal>serious</literal> unless
it is something that will affect many users (problems with
unless it really is (e.g. data corruption issues, serious
regression from previous functionality in -CURRENT)
or <literal>serious</literal> unless
it is something that will affect many users (kernel
panics or freezes; problems with
particular device drivers or system utilities). &os;
developers will not neccesarily work on your problem faster
if you inflate its importance since there are so many other
people who have done exactly that &mdash; in fact, some
developers pay little attention to this field, and the next,
developers pay little attention to this field
because of this.</para>
<note>
<para>Major security problems should <emphasis>not</emphasis>
be filed in GNATS, because all GNATS information is public
knowledge. Please send such problems in private email to
&a.security-officer;.</para>
</note>
</listitem>
<listitem>
@ -675,12 +709,40 @@
be reserved for problems that will affect practically
every user of &os; and <literal>medium</literal> for
something that will affect many users.</para>
<note>
<para>This field has become so widely abused that it is
almost completely meaningless.</para>
</note>
</listitem>
<listitem>
<para><emphasis>Category:</emphasis> Choose one of the
following (taken from
<para><emphasis>Category:</emphasis> Choose an appropriate
category.</para>
<note>
<para>There are a number of "platform" categories into which
bugs in the base system that are specific to one particular
hardware architecture should be filed. Problems that are
generic all across versions of &os; should probably be
filed as <literal>kern</literal> or <literal>bin</literal>;
see discussion of those categories below.</para>
<para>Example: you have a common PC-based machine, and think
you have encountered a problem specific to a particular
chipset or a particular motherboard: <literal>i386</literal>
is the right category.</para>
<para>Example: You are having a problem with an add-in
peripheral card on a commonly seen bus, or a problem with
a particular type of hard disk drive: in this case, it
probably applies to more than one architecture, and
<literal>kern</literal> is the right category.</para>
</note>
<para>Here is the current list of categories (taken from
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories"></ulink>):</para>
<itemizedlist>
<listitem>
<para><literal>advocacy:</literal> problems relating to
@ -699,12 +761,18 @@
<listitem>
<para><literal>bin:</literal> problems with userland
programs in the base system.</para>
programs in the base system. If running &man.whereis.1;
shows <literal>/bin</literal>, <literal>/usr/sbin</literal>,
or something similar, then this is probably the right
category. (A few contributed programs might instead
need to be in <literal>gnu</literal>; see below.)</para>
</listitem>
<listitem>
<para><literal>conf:</literal> problems with
configuration files, default values etc.</para>
configuration files, default values, and so forth.
Things that affect <literal>/usr/share</literal>
or <literal>/etc/rc*</literal> belong here.</para>
</listitem>
<listitem>
@ -713,7 +781,7 @@
</listitem>
<listitem>
<para><literal>gnu:</literal> problems with GNU software
<para><literal>gnu:</literal> problems with imported GNU software
such as &man.gcc.1; or &man.grep.1;.</para>
</listitem>
@ -736,12 +804,18 @@
<listitem>
<para><literal>kern:</literal> problems with
the kernel or (non-platform-specific) device drivers.</para>
the kernel, (non-platform-specific) device drivers,
or the base libraries.</para>
</listitem>
<listitem>
<para><literal>misc:</literal> anything that does not fit
in any of the other categories. (Note that it is
in any of the other categories. (Note that there is
almost nothing that truly belongs in this category,
except for problems with the release and build
infrastructure. Temporary build failures on
<literal>HEAD</literal> do not belong here. Also note
that it is
easy for things to get lost in this category).</para>
</listitem>
@ -777,7 +851,10 @@
<listitem>
<para><literal>www:</literal> Changes or enhancements to
the &os; website.</para>
the &os; website.
Problems with code found in <literal>/usr/ports/www</literal>
do <emphasis>not</emphasis> belong here, they belong in
<literal>ports</literal> instead.</para>
</listitem>
</itemizedlist>
</listitem>
@ -816,7 +893,8 @@
<listitem>
<para><emphasis>Release:</emphasis> The version of &os;
that you are running. This is filled out automatically by
that you are running. This is filled out automatically if
you are using
&man.send-pr.1; and need only be changed if you are
sending a problem report from a different system than the
one that exhibits the problem.</para>
@ -867,6 +945,8 @@
<section>
<title>Sending off the problem report</title>
<para>If you are using &man.send-pr.1;:</para>
<para>Once you are done filling out the template, have saved it,
and exit your editor, &man.send-pr.1; will prompt you with
<prompt>s)end, e)dit or a)bort?</prompt>. You can then hit
@ -884,6 +964,26 @@
<para>This will read the specified file, validate the contents,
strip comments and send it off.</para>
<para>If you are using the web form:</para>
<para>Before you hit <literal>submit</literal>, you will need to
fill in a field containing text that is represented in image
form on the page. This unfortunate measure has had to be
adopted due to misuse by automated systems and a few misguided
individuals. It is a necessary evil that no one likes; please
do not ask us to remove it.</para>
<para>Note that you are <literal>strongly advised</literal> to
save your work somewhere before hitting <literal>submit</literal>.
A common problem for users is to have their web browser displaying
a stale image from its cache. If this happens to you, your
submission will be rejected and you may lose your work.</para>
<para>If you are unable to view images for any reason, and are also
unable to use &man.send-pr.1;, please accept our apologies for
the inconvenience and email your problem report to the bugbuster
team at <email>freebsd-bugbusters@FreeBSD.org</email>.</para>
</section>
</section>
@ -943,6 +1043,45 @@
possible, explaining how or when the problem was fixed.</para>
</section>
<section id="pr-problems">
<title>If you are having problems</title>
<para>Most PRs go through the system and are accepted quickly;
however, at times GNATS runs behind and you may not get your
email confirmation for 10 minutes or even longer. Please try to
be patient.</para>
<para>In addition, because GNATS receives all its input via email,
it is absolutely vital that &os; runs all its submissions through
spam filters. If you do not get a response within an hour or
two, you may have fallen afoul of them; if so, please contact
the GNATS administrators at <email>bugmeister@FreeBSD.org</email>
and ask for help.</para>
<note>
<para>Among the anti-spam measures is one that weighs against
many common abuses seen HTML-based email (although not necessarily
the mere inclusion of HTML in a PR). We strongly recommend
against the use of HTML-based email when sending PRs: not
only is it more likely to fall afoul of the filters, it also
tends to merely clutter up the database. Plain old email is
strongly preferred.</para>
</note>
<para>On rare occasions you will encounter a GNATS bug where a
PR is accepted and assigned a tracking number but it does not
show up on the list of PRs on any of the web query pages. What
may have happened is that the database index has gotten out of
synchronization with the database itself. The way that you
can test whether this has happened is to pull up the
<ulink url="http://www.FreeBSD.org/cgi/query-pr.cgi">
view a single PR</ulink> page and see whether the PR shows up.
If it does, please notify the GNATS administrators at
<email>bugmeister@FreeBSD.org</email>. Note that there is a
<literal>cron</literal> job that periodically rebuilds the database,
so unless you are in a hurry, no action needs to be taken.</para>
</section>
<section id="pr-further">
<title>Further Reading</title>