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

problem-reports: bugzilla modernization

Browse source 
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 2018-08-12 08:46:43 +00:00
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
Show stats Download patch file Download diff file Expand all files Collapse all files

354
en_US.ISO8859-1/articles/problem-reports/article.xml
View file

@ -12,7 +12,6 @@
&tm-attrib.freebsd; &tm-attrib.freebsd;
&tm-attrib.ibm; &tm-attrib.ibm;
&tm-attrib.intel; &tm-attrib.intel;
&tm-attrib.sparc;
&tm-attrib.sun; &tm-attrib.sun;
&tm-attrib.general; &tm-attrib.general;
</legalnotice> </legalnotice>
@ -301,7 +300,7 @@
<itemizedlist> <itemizedlist>
<listitem> <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 line empty.</emphasis> The PRs go both onto a mailing
list that goes all over the world (where the list that goes all over the world (where the
<quote>Synopsis</quote> is used for the <quote>Synopsis</quote> is used for the
@ -375,13 +374,11 @@
<listitem> <listitem>
<para>Include which global options you have specified in <para>Include which global options you have specified in
your <filename>make.conf</filename>. Note: specifying your <filename>make.conf</filename>,
<literal>-O2</literal> and above to &man.gcc.1; is <filename>src.conf</filename>,
known to be buggy in many situations. While the &os; and <filename>src-env.conf</filename>.
developers will accept patches, they are generally Given the infinite number of options, not every
unwilling to investigate such issues due to simple combination may be fully supported.</para>
lack of time and volunteers, and may instead respond
that this just is not supported.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -594,84 +591,24 @@
</section> </section>
<section xml:id="pr-writing-filling-template"> <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 <note>
single-line fields:</para> <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> <itemizedlist>
<listitem> <listitem>
<para><emphasis>Submitter-Id:</emphasis> Do not change this. <para><emphasis>Summary:</emphasis> Fill this out with a
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&mdash;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 &mdash; 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
short and accurate description of the problem. The short and accurate description of the problem. The
synopsis is used as the subject of the problem report synopsis is used as the subject of the problem report
email, and is used in problem report listings and email, and is used in problem report listings and
@ -683,8 +620,20 @@
<literal>[patch]</literal> (including the brackets); if <literal>[patch]</literal> (including the brackets); if
this is a ports PR and you are the maintainer, you may this is a ports PR and you are the maintainer, you may
consider adding <literal>[maintainer update]</literal> consider adding <literal>[maintainer update]</literal>
(including the brackets) and set the <quote>Class</quote> (including the brackets).</para>
of your PR to <literal>maintainer-update</literal>.</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>
<listitem> <listitem>
@ -735,11 +684,8 @@
<filename class="directory">/sbin</filename>, or <filename class="directory">/sbin</filename>, or
<filename class="directory">/usr/sbin</filename>, it <filename class="directory">/usr/sbin</filename>, it
is part of the base system, and you should use the is part of the base system, and you should use the
<literal>bin</literal> category. (A few programs, <literal>bin</literal> category. These are all things
such as &man.gcc.1;, actually use the that are described in section 1 or 8 of the manual
<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
pages.</para> pages.</para>
</listitem> </listitem>
@ -754,15 +700,8 @@
<listitem> <listitem>
<para>If you have found a problem in the documentation <para>If you have found a problem in the documentation
set (articles, books, man pages), the correct choice set (articles, books, man pages) or website the
is <literal>docs</literal>.</para> 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>
<note> <note>
<para>if you are having a problem with something from <para>if you are having a problem with something from
@ -798,19 +737,6 @@
<literal>standards</literal>.</para> <literal>standards</literal>.</para>
</listitem> </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> <listitem>
<para>If you are convinced that the problem will only <para>If you are convinced that the problem will only
occur under the processor architecture you are using, occur under the processor architecture you are using,
@ -820,8 +746,8 @@
AMD machines running in 64-bit mode (this also AMD machines running in 64-bit mode (this also
includes Intel-compatible machines running in EMT64 includes Intel-compatible machines running in EMT64
mode); and less commonly <literal>arm</literal>, mode); and less commonly <literal>arm</literal>,
<literal>ia64</literal>, <literal>powerpc</literal>, <literal>ia64</literal>, and
and <literal>sparc64</literal>.</para> <literal>powerpc</literal>.</para>
<note> <note>
<para>These categories are quite often misused for <para>These categories are quite often misused for
@ -862,160 +788,8 @@
choice.</para> choice.</para>
</listitem> </listitem>
</itemizedlist> </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>
<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> <listitem>
<para><emphasis>Environment:</emphasis> This should <para><emphasis>Environment:</emphasis> This should
describe, as accurately as possible, the environment in describe, as accurately as possible, the environment in
@ -1030,56 +804,20 @@
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis>Description:</emphasis> A complete and <para><emphasis>Description:</emphasis>A complete and
accurate description of the problem you are experiencing. accurate description of the problem you are experiencing.
Try to avoid speculating about the causes of the problem Try to avoid speculating about the causes of the problem
unless you are certain that you are on the right track, as unless you are certain that you are on the right track, as
it may mislead a developer into making incorrect it may mislead a developer into making incorrect
assumptions about the problem.</para> assumptions about the problem. It should include the
</listitem> actions you need to take to reproduce the problem. If you
know any workaround, include it. It not only helps other
<listitem> people with
<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
the same problem work around it, but may also help a the same problem work around it, but may also help a
developer understand the cause for the problem), but if developer understand the cause for the problem.</para>
you do not have any firm ideas for either, it is better to
leave this field blank than to speculate.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </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>
<section xml:id="pr-followup"> <section xml:id="pr-followup">