path: root/english/Bugs/Developer.wml

#use wml::debian::template title="Debian BTS — developer info" NOHEADER=yes NOCOPYRIGHT=true
#include "$(ENGLISHDIR)/Bugs/pkgreport-opts.inc"

<h1>Information regarding the bug processing system for package
  maintainers and bug triagers</h1>

<p>Initially, a bug report is submitted by a user as an ordinary mail
message to <code>submit@bugs.debian.org</code> which must include
  a <code>Package</code> line (see <a href="Reporting">Bug Reporting
    Instructions</a> for more information).  This will then be
given a number, acknowledged to the user, and forwarded to
<code>debian-bugs-dist</code>.  If the <code>Package</code> line contains a
package which has a known maintainer,
the maintainer will get a copy too.</p>

<p>The <code>Subject</code> line will have
<code>Bug#</code><var>nnn</var><code>:</code> added, and the
<code>Reply-To</code> will be set to include both the submitter of the
report and <var>nnn</var><code>@bugs.debian.org</code>.</p>

<ul class="toc">
  <li><a href="#closing">Closing bug reports</a></li>
  <li><a href="#followup">Followup messages</a></li>
  <li><a href="#severities">Severity levels</a></li>
  <li><a href="#tags">Tags for bug reports</a></li>
  <li><a href="#forward">Recording that you have passed on a bug report</a></li>
  <li><a href="#owner">Changing bug ownership</a></li>
  <li><a href="#maintincorrect">Incorrectly listed package maintainers</a></li>
  <li><a href="#requestserv">Reopening, reassigning and manipulating bugs</a></li>
  <li><a href="#subscribe">Subscribing to bugs</a></li>
  <li><a href="#subjectscan">More-or-less obsolete subject-scanning feature</a></li>
  <li><a href="#x-debian-pr">Obsolete <code>X-Debian-PR: quiet</code> feature</a></li>
</ul>

<h2><a name="closing">Closing bug reports</a></h2>

<p>Debian bug reports should be closed when the problem is fixed. Problems
in packages can only be considered fixed once a package that includes the
bug fix enters the Debian archive.</p>

<p>Normally, the only people that should close a bug report are the
submitter of the bug and the maintainer(s) of the package against which the
bug is filed. There are exceptions to this rule, for example, the bugs filed
against unknown packages or certain generic pseudo-packages. A bug can also
be closed by any contributor if the bug is for an <strong>orphaned</strong>
package or if the maintainer of a package has missed closing it. It is very
important to mention the version in which the bug was fixed.  When in doubt,
don't close bugs, first ask for advice on the debian-devel mailing list.</p>

<p>Bug reports should be closed by sending email to
<var>nnn</var><code>-done@bugs.debian.org</code>. The message body
needs to contain an explanation of how the bug was fixed.</p>

<p>With the emails received from the bug tracking system, all you need
to do to close the bug is to make a Reply in your mail reader program
and edit the <code>To</code> field to say
<var>nnn</var><code>-done@bugs.debian.org</code> instead of
<var>nnn</var><code>@bugs.debian.org</code>
(<var>nnn</var><code>-close</code> is provided as an alias for
<var>nnn</var><code>-done</code>).</p>

<p>Where applicable, please supply a <code>Version</code> line in the
<a href="Reporting#pseudoheader">pseudo-header</a> of your message when
closing a bug, so that the bug tracking system knows which releases of the
package contain the fix.</p>

<p>The person closing the bug, the person who submitted it and the
<code>debian-bugs-closed</code> mailing list will each get a notification
about the change in status of the report. The submitter and the mailing list
will also receive the contents of the message sent to
<var>nnn</var><code>-done</code>.</p>


<h2><a name="followup">Followup messages</a></h2>

<p>The bug tracking system will include the submitter's address and the bug
address (<var>nnn</var><code>@bugs.debian.org</code>) in the <code>Reply-To</code>
header after forwarding the bug report. Please note that these are two
distinct addresses.</p>

<p>
Any developer wishing to reply to a bug report should simply reply
to the message, respecting the <code>Reply-To</code> header. This will
<strong>not</strong> close the bug.</p>

<p>Do <em>not</em> use the <q>reply to all recipients</q> or <q>followup</q>
feature of your mailer unless you intend to edit down the recipients
substantially.  In particular, see that you don't send followup messages
to <code>submit@bugs.debian.org</code>.</p>

<p>
Messages can be sent to the following addresses
in order to be filed in the bug tracking system:
</p>

<ul>
<li>
<var>nnn</var><code>@bugs.debian.org</code> — such messages are also sent
to the package maintainer and forwarded to <code>debian-bugs-dist</code>,
but <strong>not</strong> to the submitter;
</li>
<li>
<var>nnn</var><code>-submitter@bugs.debian.org</code> — these are also sent
to the submitter and forwarded to <code>debian-bugs-dist</code>,
but <strong>not</strong> to the package maintainer;
</li>
<li>
<var>nnn</var><code>-maintonly@bugs.debian.org</code> — these are only sent
to the package maintainer, <strong>not</strong> to the submitter
or <code>debian-bugs-dist</code>;
</li>
<li>
<var>nnn</var><code>-quiet@bugs.debian.org</code> —  these are only
filed in the bug tracking system (as are all the above),
<strong>not</strong> sent to anyone else.
</li>
</ul>

<p>For more information about headers to suppress ACK messages and how
to send carbon copies using the Bug Tracking System, see the
<a href="Reporting">instructions for reporting bugs</a>.</p>


<h2><a name="severities">Severity levels</a></h2>

<p>The bug system records a severity level with each bug report.  This is
set to <code>normal</code> by default, but can be overridden either by
supplying a <code>Severity</code> line in the pseudo-header when the
bug is submitted (see the
<a href="Reporting#pseudoheader">instructions for reporting
bugs</a>), or by using the <code>severity</code> command with the
<a href="#requestserv">control request server</a>.</p>

<p>The severity levels are:</p>

<dl>
<dt><code>critical</code></dt>
<dd>makes unrelated software on the system (or the whole system)
break, or causes serious data loss, or introduces a security hole on
systems where you install the package.</dd>

<dt><code>grave</code></dt>
<dd>makes the package in question unusable or mostly so, or causes
data loss, or introduces a security hole allowing access to the
accounts of users who use the package.</dd>

<dt><code>serious</code></dt>
<dd>is a <a href="$(DOC)/debian-policy/">severe
violation of Debian policy</a> (roughly, it violates a <q>must</q> or <q>required</q>
directive), or, in the package maintainer's or release manager's opinion, makes the package
unsuitable for release.</dd>

<dt><code>important</code></dt>
<dd>a bug which has a major effect on the usability of a package, without
rendering it completely unusable to everyone.</dd>

<dt><code>normal</code></dt>
<dd>the default value, applicable to most bugs.</dd>
 
<dt><code>minor</code></dt>
<dd>a problem which doesn't affect the package's usefulness, and is
presumably trivial to fix.</dd>

<dt><code>wishlist</code></dt>
<dd>for any feature request, and also for any bugs that are
very difficult to fix due to major design considerations.</dd>
</dl>

<p>Certain severities are considered
<em><a href="https://bugs.debian.org/release-critical/">release-critical</a></em>,
meaning the bug will have an impact on releasing the package with the
stable release of Debian. Currently, these are <strong>critical</strong>,
<strong>grave</strong> and <strong>serious</strong>. For complete and
canonical rules on what issues merit these severities, see the list of
<a href="https://release.debian.org/testing/rc_policy.txt">release-critical
issues for the next release</a>.</p>

<h2><a name="tags">Tags for bug reports</a></h2>

<p>Each bug can have zero or more of a set of given tags. These tags are
displayed in the list of bugs when you look at a package's page, and when
you look at the full bug log.</p>

<p>Tags can be set by supplying a <code>Tags</code> line in the
pseudo-header when the bug is submitted (see the
<a href="Reporting#pseudoheader">instructions for reporting bugs</a>),
or by using the <code>tags</code> command with the
<a href="#requestserv">control request server</a>.
Separate multiple tags with commas, spaces, or both.</p>

<p>The current bug tags are: <bts_tags>. Here is some detailed info
about the tags:</p>

<dl>

<dt><code>patch</code></dt>
  <dd>A patch or some other easy procedure for fixing the bug is included in
  the bug logs. If there's a patch, but it doesn't resolve the bug
  adequately or causes some other problems, this tag should not be used.</dd>

<dt><code>wontfix</code></dt>
  <dd>This bug won't be fixed. Possibly because this is a choice between two
  arbitrary ways of doing things and the maintainer and submitter prefer
  different ways of doing things, possibly because changing the behaviour
  will cause other, worse, problems for others, or possibly for other
  reasons.</dd>

<dt><code>moreinfo</code></dt>
  <dd>This bug can't be addressed until more information is provided by the
  submitter. The bug will be closed if the submitter doesn't provide more
  information in a reasonable (few months) timeframe. This is for bugs like
  <q>It doesn't work</q>. What doesn't work?</dd>

<dt><code>unreproducible</code></dt>
  <dd>This bug can't be reproduced on the maintainer's system.  Assistance
  from third parties is needed in diagnosing the cause of the problem.</dd>

<dt><code>help</code></dt>
<dd>The maintainer is requesting help with dealing with this bug.
  Either the maintainer does not have the skills necessary to fix this
  bug and desires collaboration, or is overloaded and wants to
  delegate this task. This bug might not be suitable for new
  contributors unless it is also tagged with the <code>newcomer</code>
  tag.</dd>

<dt><code>newcomer</code></dt>
  <dd>This bug has a known solution but the maintainer requests
  someone else implement it. This is an ideal task for new
  contributors who wish to get involved in Debian, or who wish to
  improve their skills.</dd>

<dt><code>pending</code></dt>
  <dd>A solution to this bug has been found and an upload will be made soon.</dd>

<dt><code>fixed</code></dt>
  <dd>This bug is fixed or worked around (by a non-maintainer upload, for
  example), but there's still an issue that needs to be resolved. This tag
  replaces the old <q>fixed</q> severity.</dd>

<dt><code>security</code></dt>
  <dd>This bug describes a security problem in a package (e.g., bad
  permissions allowing access to data that shouldn't be accessible; buffer
  overruns allowing people to control a system in ways they shouldn't be
  able to; denial of service attacks that should be fixed, etc). Most
  security bugs should also be set at critical or grave severity.</dd>

<dt><code>upstream</code></dt>
  <dd>This bug applies to the upstream part of the package.</dd>

<dt><code>confirmed</code></dt>
  <dd>The maintainer has looked at, understands, and basically agrees with
  the bug, but has yet to fix it. (Use of this tag is optional; it is
  intended mostly for maintainers who need to manage large numbers of open
  bugs.)</dd>

<dt><code>fixed-upstream</code></dt>
  <dd>The bug has been fixed by the upstream maintainer, but not yet in the
  package (for whatever reason: perhaps it is too complicated to backport
  the change or too minor to be worth bothering).</dd>

<dt><code>fixed-in-experimental</code></dt>
  <dd>The bug has been fixed in the package of the experimental
  distribution, but not yet in the unstable distribution.</dd>

<dt><code>d-i</code></dt>
  <dd>This bug is relevant to the development of debian-installer. It is
  expected that this will be used when the bug affects installer development
  but is not filed against a package that forms a direct part of the
  installer itself.</dd>

<dt><code>ipv6</code></dt>
  <dd>This bug affects support for Internet Protocol version 6.</dd>

<dt><code>lfs</code></dt>
  <dd>This bug affects support for large files (over 2 gigabytes).</dd>

<dt><code>l10n</code></dt>
  <dd>This bug is relevant to the localisation of the package.</dd>

<dt><code>a11y</code></dt>
  <dd>This bug affects accessibility for users with disabilities. It
  particularly impacts usability by people who rely on assistive (or
  other adaptive) technology to use the system/package.</dd>

<dt><code>ftbfs</code></dt>
  <dd>The package fails to build from source. If the bug is assigned to a
    source package, that package fails to build. If the bug is assigned
    to a binary package, the affected source packages fail to build. The
    tag is applicable to non-standard build environments (e.g. using
    Build-Depends from experimental), but the severity should be below
    serious (release critical) in such cases.</dd>

<dt><bts_release_tags></dt>
  <dd>These are release tags, which have two effects. When set on a bug,
    the bug can only affect the particular release (though it may also affect
    other releases if other release tags are set) but otherwise normal
    buggy/fixed/absent rules apply. The bug also should not be
    archived until it is fixed in the release.</dd>

<dt><bts_release_ignore_tags></dt>
  <dd>This release-critical bug is to be ignored for the purposes of
  releasing the particular release. <strong>These tags should only be used by the release
  manager(s); do not set it yourself without explicit authorization from
  them.</strong></dd>

</dl>

<p>Some info on distribution-specific tags:
  the -ignore tags ignore the bug for the purposes
  of testing propagation. The release tags indicate that the bug in
  question should not be archived until it is fixed in the set of
  releases specified. The release tags also indicate that a bug should
  only be considered buggy in the set of releases specified. [In other
  words, the bug is <strong>absent</strong> in any release whose
  corresponding release tag is <strong>not</strong> set if any release
  tags are set; otherwise the normal found/fixed rules apply.]
</p>

<p>
  Release tags should <strong>not</strong> be used if proper
  versioning of the bug would achieve the desired effect, as they
  require manual addition and removal. If you are unsure if a release
  tag is required, contact the Debian BTS Administrators
  (<email "owner@bugs.debian.org">) or the release team for advice.
</p>

<h2><a name="forward">Recording that you have passed on a bug report</a></h2>

<p>When a developer forwards a bug report to the developer of the
upstream source package from which the Debian package is derived,
they should note this in the bug tracking system as follows:</p>

<p>Make sure that the <code>To</code> field of your message to the author
has only the author(s) address(es) in it; put the person who
reported the bug,
<var>nnn</var><code>-forwarded@bugs.debian.org</code>
and <var>nnn</var><code>@bugs.debian.org</code> in the
<code>CC</code> field.</p>

<p>Ask the author to preserve the <code>CC</code> to
<var>nnn</var><code>-forwarded@bugs.debian.org</code> when they reply, so that
the bug tracking system will file their reply with the original
report. These messages are only filed and are not sent on; to send a
message as normal, send them
to <var>nnn</var><code>@bugs.debian.org</code> as well.</p>

<p>When the bug tracking system gets a message at
<var>nnn</var><code>-forwarded</code> it will mark the relevant bug as
having been forwarded to the address(es) in the <code>To</code> field
of the message it gets, if the bug is not already marked as forwarded.</p>

<p>You can also manipulate the <q>forwarded to</q> information by sending
messages to <a href="server-control"><code>control@bugs.debian.org</code></a>.</p>


<h2><a name="owner">Changing bug ownership</a></h2>

<p>In cases where the person responsible for fixing a bug is not the
assigned maintainer for the associated package (for example, when the
package is maintained by a team), it may be useful to record this fact
in the bug tracking system. To help with this, each bug may
optionally have an owner.</p>

<p>The owner can be set by supplying an <code>Owner</code> line in the
pseudo-header when the bug is submitted (see the
<a href="Reporting#pseudoheader">instructions for reporting bugs</a>),
or by using the <code>owner</code> and <code>noowner</code> commands
with the <a href="#requestserv">control request server</a>.</p>


<h2><a name="maintincorrect">Incorrectly listed package maintainers</a></h2>

<p>If the maintainer of a package is listed incorrectly, this is
usually because the maintainer has changed recently, and the new
maintainer hasn't yet uploaded a new version of the package with a
changed <code>Maintainer</code> control file field.  This will be
fixed when the package is uploaded; alternatively, the archive maintainers
can override the maintainer record of a package manually, for example if
a rebuild and reupload of the package is not expected to be needed soon.
Contact <code>override-change@debian.org</code> for changes to the
override file.</p>


<h2><a name="requestserv">Reopening, reassigning and manipulating bugs</a></h2>

<p>It is possible to reassign bug reports to other packages, to reopen
erroneously-closed ones, to modify the information saying to where, if
anywhere, a bug report has been forwarded, to change the severities
and titles of reports, to set the ownership of bugs, to merge and unmerge
bug reports, and to record the versions of packages in which bugs were
found and in which they were fixed.  This is done by sending mail to
<code>control@bugs.debian.org</code>.</p>

<p>The <a href="server-control">format of these messages</a> is
described in another document available on the World Wide Web or in
the file <code>bug-maint-mailcontrol.txt</code>.  A plain text version
can also be obtained by mailing the word <code>help</code> to the
server at the address above.</p>

<h2><a name="subscribe">Subscribing to bugs</a></h2>

<p>The bug tracking system also allows bug submitters, developers and other
interested third parties to subscribe to individual bugs. This feature can be
used by those wishing to keep an eye on a bug, without having to subscribe to a
package through the <a href="https://tracker.debian.org">Debian Package
Tracker</a>. All messages that are received at
<var>nnn</var><code>@bugs.debian.org</code>, are sent to subscribers.</p>

<p>Subscribing to a bug can be done by sending an email to
<var>nnn</var><code>-subscribe@bugs.debian.org</code>. The subject and body of
the email are ignored by the BTS. Once this message is processed, users are
sent a confirmation message that they will need to reply to before they are
sent the messages relating to that bug.</p>

<p>It is also possible to unsubscribe from a bug. Unsubscribing can be done by
sending an email to <var>nnn</var><code>-unsubscribe@bugs.debian.org</code>. The
subject and body of the email are again ignored by the BTS. Users will be sent
a confirmation message which they must reply to if they wish to be unsubscribed
from the bug.</p>

<p>By default, the address subscribed is the one found in the <code>From</code>
header. If you wish to subscribe another address to a bug, you will need to
encode the address to be subscribed into the subscription message. This takes the form of:
<var>nnn</var><code>-subscribe-</code>\
<var>localpart</var><code>=</code>\
<var>example.com</var><code>@bugs.debian.org</code>.
That example would send <code>localpart@example.com</code> a subscription message
for bug <var>nnn</var>. The <code>@</code> sign must be encoded by changing it
to an <code>=</code> sign. Similarly, an unsubscription takes the form
<var>nnn</var><code>-unsubscribe-</code><var>localpart</var>\
<code>=</code><var>example.com</var><code>@bugs.debian.org</code>.
In both cases, the subject and body of the email will be forwarded to the email
address within the request for confirmation.</p>

<h2><a name="subjectscan">More-or-less obsolete subject-scanning feature</a></h2>

<p>Messages that arrive at <code>submit</code> or <code>bugs</code> whose
Subject starts <code>Bug#</code><var>nnn</var> will be treated as
having been sent to <var>nnn</var><code>@bugs.debian.org</code>.  This is both
for backwards compatibility with mail forwarded from the old
addresses, and to catch followup mail sent to <code>submit</code> by
mistake (for example, by using reply to all recipients).</p>

<p>A similar scheme operates for <code>maintonly</code>,
<code>done</code>, <code>quiet</code> and <code>forwarded</code>,
which treat mail arriving with a Subject tag as having been sent to
the corresponding <var>nnn-whatever</var><code>@bugs.debian.org</code> address.</p>

<p>Messages arriving at plain <code>forwarded</code> and
<code>done</code> &mdash; ie, with no bug report number in the address &mdash; and
without a bug number in the Subject will be filed under <q>junk</q> and
kept for a few weeks, but otherwise ignored.</p>


<h2><a name="x-debian-pr">Obsolete <code>X-Debian-PR: quiet</code> feature</a></h2>

<p>It used to be possible to prevent the bug tracking system from
forwarding anywhere messages it received at <code>debian-bugs</code>,
by putting an <code>X-Debian-PR: quiet</code> line in the actual mail
header.</p>

<p>This header line is now ignored.  Instead, send your message to
<code>quiet</code> or <var>nnn</var><code>-quiet</code> (or
<code>maintonly</code> or <var>nnn</var><code>-maintonly</code>).</p>

<hr />

#use "otherpages.inc"

#use "$(ENGLISHDIR)/Bugs/footer.inc"