apt-listchanges
===============

******************************************************************************
Due to the demand, here is a quick overview of how apt-listchanges works.
******************************************************************************

While upgrading a package _package_, apt-listchanges does the following:

1. finds the name of its _source package_ ;
2. see if this _source package_ has already showed up in its status database
   or not, if not jump to 4 ;
3. read _package_ changelog from its .deb and append the data to the data to
   be shown ;
4. update this _source package_ as seen in the status database.

This is done for every package that is going to be installed or upgraded.

The reasons for a changelog not to show up are:
* you never installed any binary package from that source package before,
  meaning that `apt-listchanges` breaks each time a source package is renamed,
  I can't fix that ;
* there is no new changelog entry:
  - `apt-get install --reinstall`) ;
  - or you already installed a binary package from the same source and the
    same version.
* `apt-listchanges` was unable to guess the package source name (should not
  happen);
* `apt-listchanges` was unable to find the Debian changelog in the binary
  package (should not happen either).


Workaround in case of libdb downgrade or similar issues
-------------------------------------------------------

During the early months of 2008, there was an unfortunate situation
where python bumped libdb to 4.6 to then downgrade it to 4.5 later
on. That generates a situation where the apt-listchanges database was
not readable anymore because updated to libdb2.6 format but then
accessed with libdb2.5.

You can read the full discussion at http://bugs.debian.org/469221 .

In case situations like that one will happen again, we want to mention
a way to recover the database, hence without history loss (if you
remove the database, apt-listchanges will see even upgraded packages
as "new" hence showing the full changelog):

 # install utilities to handle both db4.6 and db4.5 libdb files
 aptitude install db4.6-util db4.5-util
 # define a temporary database location
 TMPDB=$(mktemp -d)/listchanges.db
 # convert the currect apt-listchanges database from 4.6 to 4.5
 db4.6_dump /var/lib/apt/listchanges.db | db4.5_load "$TMPDB"
 # keep a copy of the old db and move the converted db in place
 mv /var/lib/apt/listchanges.db /var/lib/apt/listchanges.db.old
 mv "$TMPDB" /var/lib/apt/listchanges.db

Adapt the solution to the situation you're facing.