svn commit: r45144 - head/en_US.ISO8859-1/articles/problem-reports
Eitan Adler
eadler at FreeBSD.org
Sun Jun 29 07:40:15 UTC 2014
Author: eadler
Date: Sun Jun 29 07:40:14 2014
New Revision: 45144
URL: http://svnweb.freebsd.org/changeset/doc/45144
Log:
Things are different in the bugzilla world. Partly update the
problem-reports article for this.
This isn't complete but at least provides a better starting point.
Modified:
head/en_US.ISO8859-1/articles/problem-reports/article.xml
Modified: head/en_US.ISO8859-1/articles/problem-reports/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/problem-reports/article.xml Sun Jun 29 07:40:13 2014 (r45143)
+++ head/en_US.ISO8859-1/articles/problem-reports/article.xml Sun Jun 29 07:40:14 2014 (r45144)
@@ -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 — 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 at 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 at 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 at FreeBSD.org</email>.</para>
</section>
<section xml:id="pr-further">
More information about the svn-doc-all
mailing list