-------------------------------
The Debian Package apt-listbugs
-------------------------------


Introduction
============

apt-listbugs is a tool which retrieves bug reports from the Debian
Bug Tracking System and lists them. In particular, it is intended to
be invoked before each installation or upgrade by APT, or other similar
package managers, in order to check whether the installation/upgrade is safe.

Most Debian developers, and some users, use the unstable version of
Debian, because this version is the latest snapshot which includes many
new features and packages.

APT is a great and convenient tool to let your system easily track the
latest package versions from unstable.
On the other hand, this capability can also make your system
fragile. If a broken package is uploaded to Debian unstable,
the package will soon get installed on many Debian systems.

The same reasoning holds for the testing version of Debian, even
though to a smaller extent.

apt-listbugs can help by warning its users about bugs in packages
which are about to be installed/upgraded and by giving the opportunity
to avoid or defer an unsafe installation/upgrade.

You can easily install apt-listbugs by using APT. Usually, no customization
is required. However, the use of a proxy server is recommended, in order
to reduce the number of accesses to the BTS.


How to (temporarily) disable apt-listbugs
=========================================

Sometimes you may need to disable the invocation of apt-listbugs, so
that you can run APT, or another similar package manager, without
also running apt-listbugs. Hopefully, this will happen very infrequently
and you will immediately want to re-enable apt-listbugs...  ;-)

In order to temporarily disable the invocation of apt-listbugs by APT,
there's no need to remove the package: it is enough to edit
/etc/apt/apt.conf.d/10apt-listbugs and turn the following line

    DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt";};

into a comment (by prepending the "//" comment symbol).

Or alternatively, you may just move the file out of the way:

  # mv /etc/apt/apt.conf.d/10apt-listbugs /root/

When you want to re-enable the invocation of apt-listbugs, drop the
comment symbol from the line, or move the file back to its original
location:

  # mv /root/10apt-listbugs /etc/apt/apt.conf.d/


Notes
=====

This version of apt-listbugs uses the Debian BTS SOAP interface for
bug retrieval.

apt-listbugs has a simple built-in interactive viewer. It uses the
querybts program as a back-end. To enable this feature, you need to
install the reportbug package. In addition, you can select broken
packages for pinning, to avoid automatically upgrading them. However,
pinning is not effective immediately, and requires restarting your APT
session.

The pinning will be removed by a cron.daily job, when the bugs no longer
affect the candidate version of the package.

If you install www-browser, you can view bug lists in HTML.
sensible-browser from the sensible-utils package is also available.


Need for a controlling terminal
===============================

apt-listbugs requires a controlling terminal for user interaction.
It will default to non-interactive auto-pin mode (equivalent to
options -qnF), if its standard output is not a tty.


Current Design Limitation
=========================

There is a problem with packages which have source-version and
binary-version mismatch. The BTS tracks the source version, while
apt-listbugs tracks the binary version. This conflict results in
version tracking not functioning for such packages. A popular example
of such a package is gcc.


Use of apt-cacher/apt-cacher-ng and proxy configuration
=======================================================

When installing apt-cacher or apt-cacher-ng with proxy configuration,
you will have configured APT proxy settings to use apt-cacher.
apt-listbugs will also use that configuration, and since apt-cacher
won't handle POST requests directed to the BTS, it will fail.

You will have a configuration like:

    Acquire::http { Proxy "http://CacheServerIp:3142"; };

for apt-cacher; add a specific proxy configuration line for
bugs.debian.org so that apt-listbugs can use a different
configuration:

    Acquire::http::Proxy::bugs.debian.org "DIRECT";


Use of apt-listbugs in unattended installations/upgrades
========================================================

As previously mentioned, apt-listbugs requires a console for user
interaction. This could make coexistence with unattended package
installations/upgrades (e.g.: see the cron-apt package) a little harder.

With its default configuration, apt-listbugs will stop any
automatic installation or upgrade, whenever the packages to be
installed or upgraded are affected by RC bugs. Buggy packages
will also be automatically pinned.

If you want the unattended process to upgrade the remaining packages, after
apt-listbugs has pinned all the buggy packages, you will have to
configure the unattended process to attempt the upgrade twice in a row:
the first attempt will pin all the buggy packages, if any; the second
attempt will upgrade the remaining packages.

On the other hand, if you want apt-listbugs to do nothing at all
during unattended package installations/upgrades, you may configure the
unattended process to set the APT_LISTBUGS_FRONTEND environment
variable to "none" before invoking the package manager.


Why does apt-listbugs ignore the "affects" field?
=================================================

Sometimes a bug has an effect on package A, but is actually due to
a flaw in package B. The BTS is able to track this kind of situation:
the bug report should be assigned to package B (where the bug can
actually be fixed), but marked as affecting package A, by using the
"affects" BTS command.
Nonetheless, apt-listbugs currently ignores the "affects" field.
In other words, when examining the bugs of package A, apt-listbugs
does not take bugs affecting A into account; it only looks at the bugs
actually assigned to A.
This is intentional, for the reasons explained below.

When a bug is assigned to package B, and found in version b1, but
marked as affecting package A, this may correspond to one of two
possible scenarios:

 0) the bug is actually present in B/b1, but causes breakage in
    package A; hence, do not upgrade to B/b1 if you want to avoid
    breaking package A

 1) the bug is actually present in B/b1, but only shows up when a
    given version (say, a1) of package A is installed; hence, do not
    upgrade to A/a1 if you want to prevent the bug in package B from
    showing up

In scenario 0, we should not stop an upgrade (or an installation) of
package A because of the bug that affects A: package B is the only one
which is able to introduce the bug into a system. Hence, as long as the
bug is correctly assigned to B and marked as found in version b1,
apt-listbugs will give users the opportunity to stop an upgrade to B/b1,
but, on the other hand, will ignore the bug when upgrading package A.
This is obtained by ignoring the "affects" field, which is exactly
what apt-listbugs does.

In scenario 1, stopping an upgrade to A/a1 would actually be useful,
as it would prevent the bug from showing up. However, the "affects"
field does not carry any version tracking information, unfortunately.
This means that there's no way for apt-listbugs to know that the
problematic upgrade is the one to A/a1, rather than to A/a2 or to
A/a3. And there's no way for apt-listbugs to distinguish between
scenario 0 and scenario 1, either. Hence, apt-listbugs currently
ignores the "affects" field in any case.

There's a way to work around the lack of version tracking info
for the "affects" field: whenever you find yourself in scenario 1,
file a separate bug report against package A, marking it as found in
version a1 and as blocked by the actual bug report (the one assigned
to package B). Please choose a descriptive bug report title, citing
the interaction with package B, in order to let users quickly see
whether they should worry about the issue.
The bug report against package A could request the addition of an
appropriate "Breaks: B (<< b2)" field to the control file.
Please note that b2 is the version where the actual bug in package B
is fixed, hence the bug report against A cannot be closed until the
bug in B is fixed: this is correctly expressed by the block relationship
between the two bug reports.
Anyway, please take into account that this strategy is sub-optimal
and may annoy some package maintainers!

Everything said so far holds for the apt-listbugs "apt" command.
The other apt-listbugs commands ("list" and "rss") need to behave
consistently, or otherwise they will produce misleading output.

Please note that scenario 1 could be dealt with differently, if
the BTS added version tracking info for the "affects" field,
or, maybe, if it implemented a distinct way to express scenario 1,
so that it's not confused with scenario 0 and has version tracking
info. See
http://lists.debian.org/debian-devel/2011/10/msg00446.html
http://lists.debian.org/debian-devel/2011/10/msg00502.html
for more details.
If there's consensus on this idea, a wishlist bug report should
probably be filed against the debbugs package, requesting this
new feature.


Back-ports handling
===================

When determining whether a given version of a package includes a given
bug, apt-listbugs treats a back-ported version (such as x.y-z~bpo8-r)
as if it were the corresponding official Debian package version (x.y-z).
This special handling is based on the (hopefully reasonable) assumption
that a back-port has the same bugs as the corresponding official package.


Debugging and filing bug reports against apt-listbugs
=====================================================

When there is an error, to obtain useful debugging information,
please run apt-listbugs with the debug option "-d".

If the error was encountered when using "apt-listbugs list" or
"apt-listbugs rss", just re-run the command-line with the "-d" option
added, and attach the output along with your bug report.

If the error was encountered when using "apt-listbugs apt" (within
an APT session), you may enable debug output by editing
/etc/apt/apt.conf.d/10apt-listbugs to add the debug option "-d":
the following line

    DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt";};

should become

    DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt -d";};

Then please restart the APT session, and attach the output along with
your bug report.


Hacking apt-listbugs
====================

There is so much more information about the BTS SOAP interface
available from debbugs source:
http://bugs.debian.org/debbugs-source/mainline/Debbugs/Bugs.pm


