Re: Review request for apt-listbugs template po file
Francesco Poli wrote:
> [1] http://anonscm.debian.org/gitweb/?p=apt-listbugs/apt-listbugs.git;a=blob;f=debian/README.Debian;hb=HEAD
An easier one to review. Commented original below, diff and revised
version attached.
> -------------------------------
> The Debian Package apt-listbugs
> -------------------------------
[...]
> apt-listbugs is a tool which retrieves bug reports from the Debian
> Bug Tracking System and lists them. Especially, it is intended to
Very slight false friend; s/Especially/In particular/
> be invoked before each upgrade by apt, or other similar package managers,
> in order to check whether the upgrade/installation is safe.
>
> Most Debian developers use the unstable version of Debian,
Reduce repetition by just saying "Most Debian developers, and some
users, [...]".
> and some users also use it, because this version is the latest
> snapshot which includes many features and new packages.
The features are new too - "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 possibility also makes your system
s/possibility/capability/
> break easily. If a broken package is uploaded to Debian unstable,
Say "can make your system fragile"
> 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 may be helpful by warning its users about bugs in packages
s/may be helpful/can help/
[...]
> The pinning will be removed by a cron.daily job, when the bugs no longer
> affect the package candidate version.
Say "the candidate version of the package".
[...]
> apt-listbugs requires a controlling terminal for user interaction.
> It will default to non-interactive failure mode, if its standard output
> is not a tty.
Recurring minor punctuation issue: surplus comma before "if".
(There are also one or two places where I'd have preferred caps in
things like "TTY" and "APT", but I'm ignoring them here.)
> When the command is "apt", apt-listbugs will also default to
> non-interactive failure mode, if it cannot open /dev/tty .
"When the command is 'apt'" doesn't make it clear that this is talking
about "apt-listbugs apt", an invocation that users don't typically
type in on the commandline. The way the "also" connects this sentence
with the previous one is also unclear. I would suggest:
apt-listbugs will also default to non-interactive failure mode if it
cannot open /dev/tty when running under an apt session.
> This may happen when apt-listbugs is (directly or indirectly) invoked
> inside an su -c "command" : commands invoked this way will have no
Surplus article, odd spacing (as some sort of stand-in for <code>
tags?), and a colon that should be a semicolon. Make that:
inside su -c "command";
> controlling terminal, because of a security fix applied to package
Missing article: "the package"
> login from version 1:4.1.5-1 on (see bug #628843). Hence, if you want
> to use apt-listbugs interactively, please do *not* invoke it (or the
> package manager that will invoke it) through the su -c "command"
^^
> mechanism.
>
> Also, please note that some package managers (such as aptitude, wajig,
> and possibly other ones), when run as a regular user, tend to gain root
others)
> privileges through the su -c "command" mechanism, for the actions that
^^ ^^
> need these privileges.
[...]
> apt-cacher / apt-cacher-ng and proxy configuration
^ ^
No need for space around the slash. In running text (as below), spell
it out as "or".
[...]
> If this is the desired behavior, no special action is needed: you may
> safely skip the rest of this section.
s/:/;/
> On the other hand, if you want apt-listbugs to merely show bugs,
> without stopping the installation/upgrade process, you can obtain this
> behavior, by editing /etc/apt/apt.conf.d/10apt-listbugs to add the yes
^
Surplus comma, and I'd call it the "yes" option, with quotes.
[...]
> 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
I'd punctuate that middle line as
package A; hence, do not upgrade to B/b1 if you want to avoid
>
> 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
Likewise
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
[...]
> Everything said so far holds for the apt-listbugs "apt" command.
> The other apt-listbugs commands ("list" and "rss") should behave
> consistently, or otherwise they will produce misleading output.
s/should/need to/
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
-------------------------------
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 upgrade by apt, or other similar package managers,
in order to check whether the upgrade/installation 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.
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 (/dev/tty)
==========================================
apt-listbugs requires a controlling terminal for user interaction.
It will default to non-interactive failure mode if its standard output
is not a tty.
apt-listbugs will also default to non-interactive failure mode if it
cannot open /dev/tty when running under an apt session.
This may happen when apt-listbugs is (directly or indirectly) invoked
inside su -c "command"; commands invoked this way will have no
controlling terminal, because of a security fix applied to the package
login from version 1:4.1.5-1 on (see bug #628843). Hence, if you want
to use apt-listbugs interactively, please do *not* invoke it (or the
package manager that will invoke it) through the su -c "command"
mechanism.
Also, please note that some package managers (such as aptitude, wajig,
and possibly others), when run as a regular user, tend to gain root
privileges through the su -c "command" mechanism, for the actions that
need these privileges.
Hence, if you want to use apt-listbugs interactively, please become root
*before* invoking the package manager, as in:
$ su -
Password:
# aptitude
rather than:
$ aptitude
See bug #662983 for more details on this issue.
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.
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.
If this is the desired behavior, no special action is needed; you may
safely skip the rest of this section.
On the other hand, if you want apt-listbugs to merely show bugs,
without stopping the installation/upgrade process, you can obtain this
behavior by editing /etc/apt/apt.conf.d/10apt-listbugs to add the "yes"
option "-y": the following line
DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt || exit 10";};
should become
DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs -y apt || exit 10";};
Please note that this configuration could even be made conditional:
DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs $APT_LISTBUGS_OPTS apt || exit 10";};
This way, apt-listbugs will avoid stopping the installation/upgrade
process *only* if an APT_LISTBUGS_OPTS environment variable is set to "-y".
Otherwise, if APT_LISTBUGS_OPTS is unset (or set to a zero-length
string), apt-listbugs will behave as usual.
However, such a conditional configuration is probably a bit risky,
since *anything* could be included (even by mistake) in the
APT_LISTBUGS_OPTS environment variable.
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 dummy 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.
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.
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 || exit 10";};
should become
DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt -d || exit 10";};
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
--- README.Debian.pristine 2012-07-12 12:15:48.671378745 +0100
+++ README.Debian 2012-07-12 13:15:06.843392547 +0100
@@ -7,24 +7,24 @@
============
apt-listbugs is a tool which retrieves bug reports from the Debian
-Bug Tracking System and lists them. Especially, it is intended to
+Bug Tracking System and lists them. In particular, it is intended to
be invoked before each upgrade by apt, or other similar package managers,
in order to check whether the upgrade/installation is safe.
-Most Debian developers use the unstable version of Debian,
-and some users also use it, because this version is the latest
-snapshot which includes many features and new packages.
+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 possibility also makes your system
-break easily. If a broken package is uploaded to Debian 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 may be helpful by warning its users about bugs in packages
+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.
@@ -47,7 +47,7 @@
session.
The pinning will be removed by a cron.daily job, when the bugs no longer
-affect the package candidate version.
+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.
@@ -57,22 +57,22 @@
==========================================
apt-listbugs requires a controlling terminal for user interaction.
-It will default to non-interactive failure mode, if its standard output
+It will default to non-interactive failure mode if its standard output
is not a tty.
-When the command is "apt", apt-listbugs will also default to
-non-interactive failure mode, if it cannot open /dev/tty .
+apt-listbugs will also default to non-interactive failure mode if it
+cannot open /dev/tty when running under an apt session.
This may happen when apt-listbugs is (directly or indirectly) invoked
-inside an su -c "command" : commands invoked this way will have no
-controlling terminal, because of a security fix applied to package
+inside su -c "command"; commands invoked this way will have no
+controlling terminal, because of a security fix applied to the package
login from version 1:4.1.5-1 on (see bug #628843). Hence, if you want
to use apt-listbugs interactively, please do *not* invoke it (or the
-package manager that will invoke it) through the su -c "command"
-mechanism.
+package manager that will invoke it) through the su -c "command"
+mechanism.
Also, please note that some package managers (such as aptitude, wajig,
-and possibly other ones), when run as a regular user, tend to gain root
-privileges through the su -c "command" mechanism, for the actions that
+and possibly others), when run as a regular user, tend to gain root
+privileges through the su -c "command" mechanism, for the actions that
need these privileges.
Hence, if you want to use apt-listbugs interactively, please become root
*before* invoking the package manager, as in:
@@ -95,13 +95,13 @@
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 package is gcc.
+of such a package is gcc.
-apt-cacher / apt-cacher-ng and proxy configuration
+apt-cacher/apt-cacher-ng and proxy configuration
==================================================
-When installing apt-cacher / apt-cacher-ng with 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.
@@ -128,12 +128,12 @@
automatic installation or upgrade, whenever the packages to be
installed or upgraded are affected by RC bugs.
-If this is the desired behavior, no special action is needed: you may
+If this is the desired behavior, no special action is needed; you may
safely skip the rest of this section.
On the other hand, if you want apt-listbugs to merely show bugs,
without stopping the installation/upgrade process, you can obtain this
-behavior, by editing /etc/apt/apt.conf.d/10apt-listbugs to add the yes
+behavior by editing /etc/apt/apt.conf.d/10apt-listbugs to add the "yes"
option "-y": the following line
DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt || exit 10";};
@@ -166,7 +166,7 @@
"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
+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.
@@ -175,12 +175,12 @@
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
+ 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
+ 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
@@ -212,7 +212,7 @@
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") should behave
+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
Reply to: