[Apt-listbugs-commits] [apt-listbugs] 04/05: describe the typical use case in the man page

[Francesco Poli]

This is an automated email from the git hooks/post-receive script.

frx-guest pushed a commit to branch master
in repository apt-listbugs.

commit cd060259073fcceab74a9ac91c123aec543c0bd4
Author: Francesco Poli (wintermute) <invernomuto at paranoici.org>
Date:   Tue Sep 20 00:10:17 2016 +0200

    describe the typical use case in the man page
---
 bin/apt-listbugs | 27 ++++++++++++++++++++++++++-
 debian/changelog |  2 ++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/bin/apt-listbugs b/bin/apt-listbugs
index 8ce72cd..68e8c55 100755
--- a/bin/apt-listbugs
+++ b/bin/apt-listbugs
@@ -50,9 +50,34 @@ apt-listbugs - Lists critical bugs before each APT installation/upgrade
 (({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
+compatible package managers, in order to check whether the
 installation/upgrade is safe.
 
+In the typical use case, the user is installing or upgrading a number
+of packages with APT or some other compatible package manager. Before the
+package installation or upgrade is actually performed, (({apt-listbugs}))
+is automatically invoked: it queries the Debian Bug Tracking System for
+bugs (of certain configured severities) that would be introduced into
+the system by the installation or upgrade; if any such bug is found,
+(({apt-listbugs})) warns the user and asks how to proceed. Among other
+things, the user has the opportunity to continue, to abort the installation
+or upgrade, or to pin some packages (so that the unsafe installation or
+upgrade is deferred). However, pinning is not effective immediately, and
+requires restarting the APT session (by aborting and then re-running
+the same APT command).
+
+Each package pin is automatically removed by a daily cron job, as soon as
+the corresponding bug is fixed in (or no longer affects) the package
+version available for installation or upgrade. When the pin is removed,
+the installation or upgrade of the package becomes possible again.
+
+In order for the automatic pin removal to work correctly, the daily cron
+job has to be actually executed: if the system is up and running almost
+24/7, then (({cron})) should suffice, otherwise, the installation of
+(({anacron})) is recommended. Moreover the Internet link must be working,
+while the cron job is run. Finally, the APT package lists should be
+kept up-to-date.
+
 = OPTIONS
 
 : -s ((*severities*)), --severity ((*severities*))
diff --git a/debian/changelog b/debian/changelog
index b1c7bf4..bb69868 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -9,6 +9,8 @@ apt-listbugs (0.1.19) UNRELEASED; urgency=medium
      - reformatted the whole document, to better comply with man page
        usual conventions
      - added a FILES section
+     - added an explanation of the typical use case to the DESCRIPTION
+       section
   * moved a couple of options in the online help to reflect the new option
     ordering in the man page
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/apt-listbugs/apt-listbugs.git