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

Things are different in the bugzilla world. Partly update the

Browse source 
problem-reports article for this.

This isn't complete but at least provides a better starting point.
This commit is contained in:
Eitan Adler 2014-06-29 07:40:14 +00:00
parent 7b7c822aba
commit 13ba1d0039
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45144
1 changed files with 23 additions and 156 deletions

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

@ -536,63 +536,23 @@
<section xml:id="pr-writing-before-beginning">
<title>Before Beginning</title>
<para>When using the &man.send-pr.1; program, make sure the
<envar>VISUAL</envar> (or <envar>EDITOR</envar> if
<envar>VISUAL</envar> is not set) environment variable is set
to something sensible.</para>
<para>Make sure that mail delivery is working. &man.send-pr.1;
uses mail messages for the submission and tracking of problem
reports. If mail messages cannot be sent from the machine
running &man.send-pr.1;, the problem report will not reach the
GNATS database. For details on the setup of mail on &os;, see
the <quote>Electronic Mail</quote> chapter of the &os;
Handbook at <uri
xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</para>
<para>Make sure that the mailer does not mangle the message on
its way to GNATS. In particular, if the mailer automatically
breaks lines, changes tabs to spaces, or escapes newline
characters, any patch will be rendered unusable. For the text
sections, however, we request the insertion of manual
linebreaks somewhere around 70 characters, so that the web
display of the PR will be readable.</para>
<para>Similar considerations apply to use of the
<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi"> web-based
PR submission form</link>. Note that cut-and-paste operations
can have their own side-effects on text formatting. In
certain cases it may be necessary to use &man.uuencode.1; to
ensure that patches arrive unmodified.</para>
PR submission form</link>. Be careful of cut-and-paste
operations that might change whitespace or other text
formatting.</para>
<para>Finally, if the submission is lengthy, prepare the work
offline so that nothing will be lost if there is a problem
submitting it. This can especially be a problem with the
<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web
form</link>.</para>
submitting it.</para>
</section>
<section xml:id="pr-writing-attaching-patches">
<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
name of the file proper, without the path). Just use the
<option>-a</option> command-line option to specify the names
of the files you wish to attach:</para>
<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen>
<para>Do not worry about binary files, they will be
automatically encoded so as not to upset your mail
agent.</para>
<para>When attaching a patch, be sure to use
<option>-c</option> or <option>-u</option> with &man.diff.1;
to create a context or unified diff (unified is preferred),
<option>-u</option> with &man.diff.1;
to create or unified diff
and make sure to specify the exact SVN revision numbers of the
files you modified so the developers who read your report will
be able to apply them easily. For problems with the kernel or
@ -619,14 +579,14 @@
new code which may require substantial review before
committing should be placed on a web or ftp server, and the
URL should be included in the PR instead of the patch.
Patches in email tend to get mangled, especially when GNATS is
involved, and the larger the patch, the harder it will be for
Patches in email tend to get mangled,
and the larger the patch, the harder it will be for
interested parties to unmangle it. Also, posting a patch on
the web allows you to modify it without having to resubmit the
entire patch in a followup to the original PR. Finally, large
patches simply increase the size of the database, since closed
PRs are not actually deleted but instead kept and simply
marked as <literal>closed</literal>.</para>
marked as complete.</para>
<para>You should also take note that unless you explicitly
specify otherwise in your PR or in the patch itself, any
@ -637,26 +597,6 @@
<section xml:id="pr-writing-filling-template">
<title>Filling out the Template</title>
<para>The next section applies to the email method only:</para>
<para>&man.send-pr.1; presents a template consisting of a list
of fields, some of which are pre-filled, and some of which
have comments explaining their purpose or listing acceptable
values. Do not worry about the comments; they will be removed
automatically if you do not modify them or remove them
yourself.</para>
<para>At the top of the template, below the
<literal>SEND-PR:</literal> lines, are the email headers. You
do not normally need to modify these, unless you are sending
the problem report from a machine or account that can send but
not receive mail, in which case you will want to set the
<literal>From:</literal> and <literal>Reply-To:</literal> to
your real email address. You may also want to send yourself
(or someone else) a carbon copy of the problem report by
adding one or more email addresses to the
<literal>Cc:</literal> header.</para>
<para>In the email template only, you will find the following
single-line fields:</para>
@ -690,29 +630,12 @@
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>
<note>
<para>Security problems should <emphasis>not</emphasis>
be filed in GNATS, because all GNATS information is
public knowledge. Please send such problems according
to our <link
xlink:href="http://security.freebsd.org/#how">security
report guidelines</link>.</para>
</note>
</listitem>
<listitem>
<para><emphasis>Priority:</emphasis> One of
<literal>low</literal>, <literal>medium</literal> or
<literal>high</literal>. <literal>high</literal> should
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>
<para><emphasis>Priority:</emphasis> This field indicates
how widespread the effects of this bug is likely to
be.</para>
</listitem>
@ -1197,47 +1120,22 @@
<para>If someone requests additional information from you, or you
remember or discover something you did not mention in the
initial report, please use one of two methods to submit your
followup:</para>
initial report, please submit a follow up. The number one
reason for a bug not getting fixed is lack of communication with
the originator.</para>
<itemizedlist>
<listitem>
<para>The easiest way is to use the followup link on the
<para>The easiest way is to use the comment option on the
individual PR's web page, which you can reach from the <link
xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">PR
search page</link>. Clicking on this link will bring up
an email window with the correct To: and Subject: lines
filled in (if your browser is configured to do this).</para>
</listitem>
<listitem>
<para>Alternatively, you can just mail it to &a.bugfollowup;,
making sure that the tracking number is included in the
subject so the bug tracking system will know what problem
report to attach it to.</para>
<note>
<para>If you do <emphasis>not</emphasis> include the
tracking number, GNATS will become confused and create an
entirely new PR which it then assigns to the GNATS
administrator, and then your followup will become lost
until someone comes in to clean up the mess, which could
be days or weeks afterwards.</para>
<para>Wrong way:</para>
<programlisting>Subject: that PR I sent</programlisting>
<para>Right way:</para>
<programlisting>Subject: Re: ports/12345: compilation problem with foo/bar</programlisting>
</note>
search page</link>.</para>
</listitem>
</itemizedlist>
<para>If the problem report remains open after the problem has
gone away, just send a follow-up (in the manner prescribed
above) saying that the problem report can be closed, and, if
gone away, just add a comment
saying that the problem report can be closed, and, if
possible, explaining how or when the problem was fixed.</para>
<para>Sometimes there is a delay of a week or two where the
@ -1298,41 +1196,10 @@
<section xml:id="pr-problems">
<title>If There Are 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 in 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
<link xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">view
a single PR</link> 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>
<para>If you found an issue with the bug system, file a bug!
There is a category for exactly this purpose. If you are unable
to do so, contact the bug wranglers at
<email>bugmeister@FreeBSD.org</email>.</para>
</section>
<section xml:id="pr-further">