<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>
+<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.
+as described below.</p>
-<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>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>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>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 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 should start at the very start of their lines.
-The $gBug system does not currently understand MIME or PGP mail properly
-and may fail to recognise the pseudo-headers in such mail.)
+<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
-<p><em>See below for <a href="#details">further requirements</a></em>.
+<p>The pseudo-header fields should start at the very start of their lines.</p>
$gHTMLPseudoDesc
+<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:
+
<pre>
To: submit\@$gEmailDomain
From: diligent\@testing.linux.org
Subject: Hello says `goodbye'
- <A name="pseudoheader">Package: hello</a>
+
+ Package: hello
Version: 1.3-16
When I invoke `hello' without arguments from an ordinary shell
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>
-
-<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>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>
to the address(es) in the <code>X-Debbugs-CC</code> line as well as to
any mailing list.
+<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.
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 pseudo-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>
any forwarded message so that replies will by default be processed in
the same way as the original report.
+
+<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
projects / debbugs.git / blobdiff