Sometimes, it is necessary for a package to get a new name. Although this should rather seldom be the case, there are some situations when it makes sense, for example when the name of the upstream application changes. Of course an apt-get dist-upgrade should still seamlessly upgrade the package, best by completely removing the old package and installing the new one as a replacement.
Basically, the solution is to define a binary dummy package with the same name as the old package in the control file of the new package. The new source package takes over the binary dummy package, and the old source package, which is then binaryless, will be cleaned up by rene, an archive cleanup tool.
Assumed that the last upstream version of the old package "oldPkg" was 1.5 and the package was renamed to "newPkg" for version 2.0.
Then, the dummy package is defined like this in debian/control:
Package: oldPkg Depends: newPkg Architecture: All Description: transitional dummy package
This entry defines the binary dummy package. It will get version 2.0 and automatically be pulled in by an apt-get dist-upgrade if an earlier version of oldPkg was already installed.
Since it depends on newPkg, it also installs the new package.
Note that the package does not contain any architecture specific files anymore and therefore the Architecture is set to "All", even if it was "Any" before.
The new package is defined like this:
Package: newPkg Provides: oldPkg Replaces: oldPkg (<< 2.0)
The Provides: entry makes sure that reverse dependencies do net get broken so that other packages which depend on the old unversioned package name can still be installed.
Method B (NOT CURRENTLY APPLICABLE)
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.