problem-reports: bugzilla modernization
This is a simple pass over the problem-reports article to make it better describe Bugzilla. It isn't perfect, still needing content, but baby-steps.
This commit is contained in:
Eitan Adler
parent
93329a27b5
commit
5fa9773384
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=52112
1 changed files with 46 additions and 308 deletions
|
|
@ -12,7 +12,6 @@
|
|||
&tm-attrib.freebsd;
|
||||
&tm-attrib.ibm;
|
||||
&tm-attrib.intel;
|
||||
&tm-attrib.sparc;
|
||||
&tm-attrib.sun;
|
||||
&tm-attrib.general;
|
||||
</legalnotice>
|
||||
|
|
@ -301,7 +300,7 @@
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis>Do not leave the <quote>Synopsis</quote>
|
||||
<para><emphasis>Do not leave the <quote>Summary</quote>
|
||||
line empty.</emphasis> The PRs go both onto a mailing
|
||||
list that goes all over the world (where the
|
||||
<quote>Synopsis</quote> is used for the
|
||||
|
|
@ -375,13 +374,11 @@
|
|||
|
||||
<listitem>
|
||||
<para>Include which global options you have specified in
|
||||
your <filename>make.conf</filename>. Note: specifying
|
||||
<literal>-O2</literal> and above to &man.gcc.1; is
|
||||
known to be buggy in many situations. While the &os;
|
||||
developers will accept patches, they are generally
|
||||
unwilling to investigate such issues due to simple
|
||||
lack of time and volunteers, and may instead respond
|
||||
that this just is not supported.</para>
|
||||
your <filename>make.conf</filename>,
|
||||
<filename>src.conf</filename>,
|
||||
and <filename>src-env.conf</filename>.
|
||||
Given the infinite number of options, not every
|
||||
combination may be fully supported.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -594,84 +591,24 @@
|
|||
</section>
|
||||
|
||||
<section xml:id="pr-writing-filling-template">
|
||||
<title>Filling out the Template</title>
|
||||
<title>Filling out the Form</title>
|
||||
|
||||
<para>In the email template only, you will find the following
|
||||
single-line fields:</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>
|
||||
|
||||
<para>When you file a bug, you will find the following
|
||||
fields:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis>Submitter-Id:</emphasis> Do not change this.
|
||||
The default value of <literal>current-users</literal> is
|
||||
correct, even if you run &os.stable;.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Confidential:</emphasis> This is prefilled
|
||||
to <literal>no</literal>. Changing it makes no sense as
|
||||
there is no such thing as a confidential &os; problem
|
||||
report—the PR database is distributed
|
||||
worldwide.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Severity:</emphasis> One of
|
||||
<literal>non-critical</literal>,
|
||||
<literal>serious</literal> or <literal>critical</literal>.
|
||||
Do not overreact; refrain from labeling your problem
|
||||
<literal>critical</literal> 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
|
||||
necessarily 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 because of this.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Priority:</emphasis> This field indicates
|
||||
how widespread the effects of this bug is likely to
|
||||
be.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
<para>The next section describes fields that are common to both
|
||||
the email interface and the
|
||||
<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web
|
||||
interface</link>:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<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.</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>
|
||||
<para><emphasis>Organization:</emphasis> Whatever you feel
|
||||
like. This field is not used for anything
|
||||
significant.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Synopsis:</emphasis> Fill this out with a
|
||||
<para><emphasis>Summary:</emphasis> Fill this out with a
|
||||
short and accurate description of the problem. The
|
||||
synopsis is used as the subject of the problem report
|
||||
email, and is used in problem report listings and
|
||||
|
|
@ -683,8 +620,20 @@
|
|||
<literal>[patch]</literal> (including the brackets); if
|
||||
this is a ports PR and you are the maintainer, you may
|
||||
consider adding <literal>[maintainer update]</literal>
|
||||
(including the brackets) and set the <quote>Class</quote>
|
||||
of your PR to <literal>maintainer-update</literal>.</para>
|
||||
(including the brackets).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Severity:</emphasis> One of
|
||||
<literal>Affects only me</literal>,
|
||||
<literal>Affcts some people</literal> or <literal>Affects
|
||||
many people</literal>.
|
||||
Do not overreact; refrain from labeling your problem
|
||||
<literal>Affects many people</literal> unless it really
|
||||
does. &os; developers will not
|
||||
necessarily work on your problem faster if you inflate its
|
||||
importance since there are so many other people who have
|
||||
done exactly that.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -735,11 +684,8 @@
|
|||
<filename class="directory">/sbin</filename>, or
|
||||
<filename class="directory">/usr/sbin</filename>, it
|
||||
is part of the base system, and you should use the
|
||||
<literal>bin</literal> category. (A few programs,
|
||||
such as &man.gcc.1;, actually use the
|
||||
<literal>gnu</literal> category, but do not worry
|
||||
about that for now.) These are all things that are
|
||||
described in section 1 or 8 of the manual
|
||||
<literal>bin</literal> category. These are all things
|
||||
that are described in section 1 or 8 of the manual
|
||||
pages.</para>
|
||||
</listitem>
|
||||
|
||||
|
|
@ -754,15 +700,8 @@
|
|||
|
||||
<listitem>
|
||||
<para>If you have found a problem in the documentation
|
||||
set (articles, books, man pages), the correct choice
|
||||
is <literal>docs</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If you are having a problem with the <link
|
||||
xlink:href="http://www.FreeBSD.org">FreeBSD web
|
||||
pages</link>, the proper choice is
|
||||
<literal>www</literal>.</para>
|
||||
set (articles, books, man pages) or website the
|
||||
correct choice is<literal>docs</literal>.</para>
|
||||
|
||||
<note>
|
||||
<para>if you are having a problem with something from
|
||||
|
|
@ -798,19 +737,6 @@
|
|||
<literal>standards</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If the problem has to do with errors internal to a
|
||||
&java.virtual.machine; (&jvm;), even though &java; was
|
||||
installed from the Ports Collection, you should select
|
||||
the <literal>java</literal> category. More general
|
||||
problems with &java; ports still go under
|
||||
<literal>ports</literal>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>This leaves everything else.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>If you are convinced that the problem will only
|
||||
occur under the processor architecture you are using,
|
||||
|
|
@ -820,8 +746,8 @@
|
|||
AMD machines running in 64-bit mode (this also
|
||||
includes Intel-compatible machines running in EMT64
|
||||
mode); and less commonly <literal>arm</literal>,
|
||||
<literal>ia64</literal>, <literal>powerpc</literal>,
|
||||
and <literal>sparc64</literal>.</para>
|
||||
<literal>ia64</literal>, and
|
||||
<literal>powerpc</literal>.</para>
|
||||
|
||||
<note>
|
||||
<para>These categories are quite often misused for
|
||||
|
|
@ -862,160 +788,8 @@
|
|||
choice.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>Here is the current list of categories (taken from
|
||||
<uri
|
||||
xlink:href="https://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">https://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>advocacy:</literal> problems relating to
|
||||
&os;'s public image. Obsolete.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>amd64:</literal> problems specific to the
|
||||
AMD64 platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>arm:</literal> problems specific to the
|
||||
ARM platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>bin:</literal> problems with userland
|
||||
programs in the base system.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>conf:</literal> problems with
|
||||
configuration files, default values, and so
|
||||
forth.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>docs:</literal> problems with manual
|
||||
pages or on-line documentation.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>gnu:</literal> problems with imported GNU
|
||||
software such as &man.gcc.1; or &man.grep.1;.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>i386:</literal> problems specific to the
|
||||
&i386; platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>ia64:</literal> problems specific to the
|
||||
ia64 platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>java:</literal> problems related to the
|
||||
&java; Virtual Machine.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>kern:</literal> problems with
|
||||
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 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>
|
||||
|
||||
<listitem>
|
||||
<para><literal>ports:</literal> problems relating to the
|
||||
Ports Collection.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>powerpc:</literal> problems specific to
|
||||
the &powerpc; platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>sparc64:</literal> problems specific to
|
||||
the &sparc64; platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>standards:</literal> standards
|
||||
conformance issues.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>threads:</literal> problems related to
|
||||
the &os; threads implementation (especially on
|
||||
&os.current;).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>usb:</literal> problems related to the
|
||||
&os; USB implementation.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>www:</literal> changes or enhancements to
|
||||
the &os; website.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Class:</emphasis> Choose one of the
|
||||
following:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>sw-bug:</literal> software bugs.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>doc-bug:</literal> errors in
|
||||
documentation.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>change-request:</literal> requests for
|
||||
additional features or changes in existing
|
||||
features.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>update:</literal> updates to ports or
|
||||
other contributed software.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>maintainer-update:</literal> updates to
|
||||
ports for which you are the maintainer.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Release:</emphasis> The version of &os;
|
||||
that you are running. This
|
||||
needs to be filled in.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>Finally, there is a series of multi-line fields:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis>Environment:</emphasis> This should
|
||||
describe, as accurately as possible, the environment in
|
||||
|
|
@ -1030,56 +804,20 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Description:</emphasis> A complete and
|
||||
<para><emphasis>Description:</emphasis>A complete and
|
||||
accurate description of the problem you are experiencing.
|
||||
Try to avoid speculating about the causes of the problem
|
||||
unless you are certain that you are on the right track, as
|
||||
it may mislead a developer into making incorrect
|
||||
assumptions about the problem.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>How-To-Repeat:</emphasis> A summary of the
|
||||
actions you need to take to reproduce the problem.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Fix:</emphasis> Preferably a patch, or at
|
||||
least a workaround (which not only helps other people with
|
||||
assumptions about the problem. It should include the
|
||||
actions you need to take to reproduce the problem. If you
|
||||
know any workaround, include it. It not only helps other
|
||||
people with
|
||||
the same problem work around it, but may also help a
|
||||
developer understand the cause for the problem), but if
|
||||
you do not have any firm ideas for either, it is better to
|
||||
leave this field blank than to speculate.</para>
|
||||
developer understand the cause for the problem.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section xml:id="pr-writing-sending">
|
||||
<title>Sending the Problem Report</title>
|
||||
|
||||
<para>If you are using the <link
|
||||
xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web form</link>:</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,
|
||||
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>
|
||||
|
||||
<section xml:id="pr-followup">
|
||||
|
|
|
|||
Loading…
Reference in a new issue