$gReportingHtml = <<HTML_END
-<html><head><title>$gProject $gBugs - how to report a $gBug</title>
-<link rev="made" href="mailto:$gMaintainerEmail">
-</head><body>
+<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>$gProject $gBugs - how to report a $gBug</title>
+ <link rev="made" href="mailto:$gMaintainerEmail">
+ <link rel="stylesheet" href="$gWebHostBugDir/css/bugs.css" type="text/css">
+</head>
+<body>
+
<h1>How to report a $gBug in $gProject</h1>
-Send mail to
-<A href="mailto:submit\@$gEmailDomain"><code>submit\@$gEmailDomain</code></A>,
-as described below.
-<p>
-
-Please don't report several unrelated $gBugs - especially ones in
-different packages - in one message. Also, please don't mail your $gBug
-report to any mailing lists or recipients other than
-<code>submit\@$gEmailDomain</code> (for details of how to do this right, see
-<A href="#xcc">below</A>).
-<p>
-
-Lists of currently-outstanding $gBugs are available <A href="./">on
-the World Wide Web</A> and <A href="Access.html">elsewhere</A> - see
-other documents for details.
-<p>
-
-You should put a pseudo-header at the start of the body of the
-message, with the <code>Package:</code> and <code>Version:</code>
-lines giving the name and version of the package which has the $gBug.
-(The pseudo-header fields must start at the very start of their lines,
-and the $gBug system does not currently understand them if they're
-buried in MIMEd or PGPd mail.)
+<h2>Important things to note <strong>before</strong> sending</h2>
+
+<p>Please don't report multiple unrelated $gBugs - especially ones in
+different packages - in a single $gBug report. It makes our lives much
+easier if you send separate reports.
+
+<p>You should check if your $gBug report has already been filed by someone
+else before submitting it. Lists of currently outstanding $gBugs are
+available <a href="./">on the World Wide Web</a> and
+<a href="Access.html">elsewhere</a> - see other documents for details.
+You can submit your comments to an existing $gBug report
+#<var><number></var> by sending e-mail to
+<var><number></var>\@$gEmailDomain</p>
+
+<p>If you can't seem to determine which package contains the problem,
+please send e-mail to the <a href="mailto:$gMaintainerEmail">
+$gMaintainerEmail</a> asking for advice.
+$gHTMLPseudoDesc
+</p>
+
+<p>If you'd like to send a copy of your $gBug report to additional
+recipients (such as mailing lists), you shouldn't use the usual e-mail
+headers, but <a href="#xcc">a different method, described below</a>.</p>
+
+
+<h2>Sending the bug report using an automatic bug report tool</h2>
+
+<p>There is a program that was developed in Debian to help reporting
+$gBug reports, it's called
+<code><a href="http://packages.debian.org/stable/utils/reportbug">reportbug</a></code>.
+It will guide you through the bug reporting process step by step,
+and probably ease filing bugs that way.</p>
+
+<p>Emacs users can also use the debian-bug command provided by the
+<code><a href="http://packages.debian.org/stable/utils/debbugs-el">
+debbugs-el</a></code> package. When called with <kbd>M-x
+debian-bug</kbd>, it will ask for all necessary information in a
+similar way to <code>reportbug</code>.</p>
+
+
+<h2>Sending the bug report via e-mail</h2>
+
+<p>Send mail to
+<a href="mailto:submit\@$gEmailDomain"><code>submit\@$gEmailDomain</code></a>,
+as described below.</p>
+
+<p>Of course, like with any email, you should include a clear, descriptive
+<code>Subject</code> line in your main mail header. The subject you
+give will be used as the initial $gBug title in the tracking system, so
+please try to make it informative!</p>
+
+<p>You need to put a <a name="pseudoheader">pseudo-header</a> at the start
+of the body of the message. That means that the first line of the message
+body should say:</p>
+
+<pre>
+Package: <something>
+</pre>
+
+<p>Replace <code><something></code> with the name of the package which
+has the $gBug.</p>
+
+<p>The second line of the message should say:</p>
+
+<pre>
+Version: <something>
+</pre>
+
+<p>Replace <code><something></code> with the version of the package.
+Please don't include any text here other than the version itself, as the
+$gBug tracking system relies on this field to work out which releases are
+affected by the bug.</p>
+
+<p>You need to supply a correct <code>Package</code> line in the
+pseudo-header in order for the $gBug tracking system to deliver the message
+to the package's maintainer.</p>
$gHTMLFindPackage
-<em>See below for <A href="#details">further requirements</A></em>.
-<p>
+<p>The pseudo-header fields should start at the very start of their lines.</p>
$gHTMLPseudoDesc
-<h2><A name="example">Example</A></h2>
+<p>Please include in your report:</p>
+
+<ul>
+ <li>The <em>exact</em> and <em>complete</em> text of any error
+ messages printed or logged. This is very important!
+ <li>Exactly what you typed or did to demonstrate the problem.
+ <li>A description of the incorrect behaviour: exactly what behaviour
+ you were expecting, and what you observed. A transcript of an
+ example session is a good way of showing this.
+ <li>A suggested fix, or even a patch, if you have one.
+ <li>Details of the configuration of the program with the problem.
+ Include the complete text of its configuration files.
+
+$gXtraBugInfo
+
+</ul>
+
+<p>Include any detail that seems relevant - you are in very little danger
+of making your report too long by including too much information. If
+they are small please include in your report any files you were using
+to reproduce the problem (uuencoding them if they may contain odd
+characters etc.).</p>
+
+
+<h2><A name="example">Example</a></h2>
+
+<p>A $gBug report, with mail header, looks something like this:
-A $gBug report, with mail header, looks something like this:
<pre>
To: submit\@$gEmailDomain
From: diligent\@testing.linux.org
Subject: Hello says `goodbye'
-<A name="psuedoheader">Package: hello</A>
- Version: 1.3-2
+
+ Package: hello
+ Version: 1.3-16
When I invoke `hello' without arguments from an ordinary shell
prompt it prints `goodbye', rather than the expected `hello, world'.
I suggest that the output string, in hello.c, be corrected.
- I am using Debian 1.1, kernel version 1.3.99.15z
- and libc 5.2.18.3.2.1.3-beta.
+ I am using Debian GNU/Linux 2.2, kernel 2.2.17-pre-patch-13
+ and libc6 2.1.3-10.
</pre>
-<h2><A name="details">Please include in your report:</A></h2>
-
-<ul>
-<li>The <em>exact</em> and <em>complete</em> text of any error
-messages printed or logged. This is very important!
-<li>Exactly what you typed or did to demonstrate the problem.
-<li>A description of the incorrect behaviour: exactly what behaviour
-you were expecting, and what you observed. A transcript of an
-example session is a good way of showing this.
-<li>A suggested fix, or even a patch, if you have one.
-<li>Details of the configuration of the program with the problem.
-Include the complete text of its configuration files.
-$gXtraBugInfo
-</ul>
-
-Include any detail that seems relevant - you are in very little danger
-of making your report too long by including too much information. If
-they are small please include in your report any files you were using
-to reproduce the problem (uuencoding them if they may contain odd
-characters etc.).
-
-<p>
-Of course, like any email, you should include a clear, descriptive
-<code>Subject</code> line in your main mail header. The subject you
-give will be used as the initial $gBug title in the tracking system, so
-please try to make it informative !
+<h2><A name="xcc">Sending copies of $gBug reports to other addresses</a></h2>
-<h2><A name="xcc">Sending copies of $gBug reports to other addresses</A></h2>
-
-Sometimes it is necessary to send a copy of a $gBug report to somewhere
+<p>Sometimes it is necessary to send a copy of a $gBug report to somewhere
else besides the mailing list and the package maintainer, which is where they
are normally sent.
-<p>
-You could do this by CC'ing your $gBug report to the other address(es),
+<p>You could do this by CC'ing your $gBug report to the other address(es),
but then the other copies would not have the $gBug report number put in
the <code>Reply-To</code> field and the <code>Subject</code> line.
When the recipients reply they will probably preserve the
<code>submit\@$gEmailDomain</code> entry in the header and have their
message filed as a new $gBug report. This leads to many duplicated
reports.
-<p>
-The <em>right</em> way to do this is to use the
-<code>X-$gProject-CC</code> header. Add a line like this to your
-message's mail header (not to the psuedo header with the
-<code>Package</code> field):
+<p>The <em>right</em> way to do this is to use the <code>X-Debbugs-CC</code>
+header. Add a line like this to your message's mail header (<em>not</em>
+to the pseudo header with the <code>Package</code> field):
<pre>
- X-$gProject-CC: other-list\@cosmic.edu
+ X-Debbugs-CC: other-list\@cosmic.edu
</pre>
This will cause the $gBug tracking system to send a copy of your report
-to the address(es) in the <code>X-$gProject-CC</code> line as well as to
+to the address(es) in the <code>X-Debbugs-CC</code> line as well as to
any mailing list.
-<p>
-This feature can often be combined usefully with mailing
+<p>Avoid sending such copies to the addresses of other $gBug reports, as
+they will be caught by the checks that prevent mail loops. There is
+relatively little point in using <code>X-Debbugs-CC</code> for this
+anyway, as the $gBug number added by that mechanism will just be
+replaced by a new one; use an ordinary <code>CC</code> header instead.
+
+<p>This feature can often be combined usefully with mailing
<code>quiet</code> - see below.
-<h2><A name="severities">Severity levels</A></h2>
+<h2><A name="severities">Severity levels</a></h2>
-If a report is of a particularly serious $gBug, or is merely a feature
+<p>If a report is of a particularly serious $gBug, or is merely a feature
request that, you can set the severity level of the $gBug as you report
it. This is not required, however, and the developers will assign an
appropriate severity level to your report if you do not.
-<p>
-To assign a severity level put a
-<code>Severity: <var>severity</var></code> line in the psuedo-header,
-together with <code>Package</code> and <code>Version</code>. The
-severity levels available are described in the
-<A href="Developer.html#severities">developers' documentation</A>.
+<p>To assign a severity level, put a line like this one in the
+<a href="#pseudoheader">pseudo-header</a>:</p>
+
+<pre>
+Severity: <<var>severity</var>>
+</pre>
+
+<p>Replace <<var>severity</var>> with one of the available severity
+levels, as described in the
+<a href="Developer.html#severities">developers' documentation</a>.</p>
+
+
+<h2><a name="tags">Assigning tags</a></h2>
+
+<p>You can set tags on a $gBug as you are reporting it. For example, if
+you are including a patch with your $gBug report, you may wish to set
+the <code>patch</code> tag. This is not required, and the developers
+will set tags on your report as and when it is appropriate.
+
+<p>To set tags, put a line like this one in the
+<a href="#pseudoheader">pseudo-header</a>:</p>
+
+<pre>
+Tags: <<var>tags</var>>
+</pre>
+
+<p>Replace <<var>tags</var>> with one or more of the available tags,
+as described in the
+<a href="Developer.html#tags">developers' documentation</a>.
+Separate multiple tags with commas, spaces, or both.
+
+<pre>
+User: <<var>username</var>>
+Usertags: <<var>usertags</var>>
+</pre>
+
+<p>Replace <<var>usertags</var>> with one or more usertags.
+Separate multiple tags with commas, spaces, or both. If you specify a
+username, that users tags will be set. Otherwise, the email address of
+the sender will be used as the username</p>
<h2>Not forwarding to the mailing list - minor $gBug reports</h2>
-If a $gBug report is minor (for example, a documentation typo or other
+<p>If a $gBug report is minor (for example, a documentation typo or other
trivial build problem), or you're submitting many reports at once,
-send them to <code>maintonly\@$gEmailDomain</code> or <code>quiet\@$gEmailDomain</code>.
+send them to <code>maintonly\@$gEmailDomain</code> or
+<code>quiet\@$gEmailDomain</code>.
<code>maintonly</code> will send the report on to the package
maintainer (provided you supply a correct <code>Package</code> line in
the pseudo-header and the maintainer is known), and <code>quiet</code>
will not forward it anywhere at all but only file it as a $gBug (useful
if, for example, you are submitting many similar $gBugs and want to post
only a summary).
-<p>
-If you do this the $gBug system will set the <code>Reply-To</code> of
+<p>If you do this the $gBug system will set the <code>Reply-To</code> of
any forwarded message so that replies will by default be processed in
the same way as the original report.
-<h3>Unknown packages or $gBugs with no <code>Package</code> key</h3>
-If the $gBug tracking system doesn't know who the maintainer of the
+<h2>Acknowledgements</h2>
+
+<p>Normally, the $gBug system will return an acknowledgement to you by
+e-mail when you report a new bug or submit additional information to an
+existing bug. If you want to suppress this acknowledgement, include an
+<code>X-Debbugs-No-Ack</code> header in your e-mail (the contents of this
+header do not matter; however, it must be in the mail header and
+<em>not</em> in the pseudo-header with the <code>Package</code> field). If
+you report a new $gBug with this header, you will need to check the web
+interface yourself to find the $gBug number.</p>
+
+<p>Note that this header will not suppress acknowledgements from the
+<code>control\@$gEmailDomain</code> mailserver, since those acknowledgements
+may contain error messages which should be read and acted upon.</p>
+
+
+<h3>$gBug reports against unknown packages</h3>
+
+<p>If the $gBug tracking system doesn't know who the maintainer of the
relevant package is it'll forward the report to
the mailing list even if <code>maintonly</code> was used.
-<p>
-When sending to <code>maintonly\@$gEmailDomain</code> or
+<p>When sending to <code>maintonly\@$gEmailDomain</code> or
<var>nnn</var><code>-maintonly\@$gEmailDomain</code> you should make sure that
the $gBug report is assigned to the right package, by putting a correct
<code>Package</code> at the top of an original submission of a report,
-or by using <A href="server-control.html">the
-<code>control\@$gEmailDomain</code> service</A> to (re)assign the report
+or by using <a href="server-control.html">the
+<code>control\@$gEmailDomain</code> service</a> to (re)assign the report
appropriately first if it isn't correct already.
$gXtraReportingInfo
<hr>
-Other pages:
-<ul>
-<li><A href="./">Bug tracking system main contents page.</A>
-<li><A href="Developer.html">Developers'
-information regarding the $gBug processing system.</A>
-<li><A href="Access.html">Accessing the $gBug tracking logs other than by WWW.</A>
-<li><A href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</A>
-<li><A href="db/ix/packages.html">Packages with $gBug reports.</A>
-<li><A href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</A>
+<p>Other pages:
+<ul>
+ <li><a href="./">Bug tracking system main contents page.</a>
+ <li><a href="Developer.html">Developers' information regarding the $gBug processing system.</a>
+ <li><a href="Access.html">Accessing the $gBug tracking logs other than by WWW.</a>
+ <li><a href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</a>
+ <li><a href="db/ix/packages.html">Packages with $gBug reports.</a>
+ <li><a href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</a>
$gHTMLOtherPageList
-
</ul>
-$gHTMLEnd
+$gHTMLTail
HTML_END
projects / debbugs.git / blobdiff