Why?

Sometimes, it is necessary for a package to get a new name. Although it should rather seldom be the case, there are some situations when this makes sense, for example when the name of the upstream application changes. Of course an apt-get dist-upgrade should seamless upgrade the package, best by completely removing the old package and installing the new one as a replacement.

Method A

 Package: oldpkg
 Depends: newpkg
 Version: 1.0
 Description: transitional dummy package

 Package: newpkg
 Replaces: oldpkg (<< 1.0)

Method B

There is an even more elegant way which installs less files and effectively provides a real replacement mechanism.

The dummy package is defined like this in debian/control:

 Package: oldpkg
 Depends: newpkg

The dummy package only installs a link (and nothing else!) like /usr/share/doc/oldpkg -> /usr/share/doc/newpkg, for example with the dh_link debhelper script.

The new package is defined like this in debian/control:

 Package: newpkg
 Replaces: oldpkg
 Provides: oldpkg

The new package installs all its necessary files and the same link as the dummy package, /usr/share/doc/oldpkg -> /usr/share/doc/newpkg

Now, when an earlier version of the oldPkg is installed and the system is upgraded with apt-get dist-upgrade, the new version of the dummy package is installed which pulls in the new package newPkg. The link is then taken over by newPkg, so that no installed files remain for the old dummy package oldPkg. dpkg is aware of this situation and notices that oldPkg is now completely replaced. However, through a bug in dpkg, it tries to configure the old dummy package at a later time, which fails because the package was already removed. Thus, at least for etch, this approach can not be used.