Major additions of text to this article:
- 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:
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
|
@ -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 — 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>
|
||||
|
||||
|
|
Loading…
Reference in a new issue