How do I gracefully retire a package?

Question

I maintain a LaTeX package which is obsolete. All its useful commands are provided by other packages, possibly with different syntax, but still the point is there is no reason for anyone to use my package anymore. Anyone who wants its functionality should use the other packages that replace it.

Are there any best practices I should use to "retire" my package? In other words, to push people away from using it and toward the other packages that replace it?

As an extreme example, one thing I could do is upload a new version of my package to CTAN in which the entire contents is deleted and replaced with

\PackageError{mypackage}{mypackage is obsolete!}{%
  See the documentation for what you should be using instead}

or something along those lines. This would more or less force people to stop using my package. But according to this answer it's desirable that old LaTeX documents should still compile correctly, and this extreme solution spoils that. Perhaps deprecation using a \PackageWarning would be better? Or something else entirely? (Does CTAN have any special support for deprecating a package?)

But again, that is only an example. I am asking for any best practices that are recognized by experienced package authors, or have been successfully used in the past, when it comes time to mark a package as obsolete.

Answer 1

I don't think that there is a single best practice --- it partly depends in what way your package has become obsolete.

One of the strong goals of LaTeX is continued backward compatibility, i.e., the ability to reprocess old documents successfully even after a long period of time and in fact that is something tat most of the time works surprisingly well (e.g., even LaTeX 2.09 documents usually compile straight away even though they give you a bold warning).

To make this possible old/obsolete packages need to be still around and available in some shape or form.

Now how they are being available depends on the nature of "obsolete": if your package has enhanced some functionality of some other package and this is now incorporated in the other package (perhaps with a slightly different interface) the best way forward may be to simply to emulate your package using the current one. For example in the graphics space many packages existed initially (epsfig, rotating, ...) and I think all of them are, but rotating for example, nowadays only preserves its interface (options) but then internally passes everything to the graphics package to do the work.

If, however, your package (or class) cuts across many other packages and provides functionality extensions here and there this approach may not be viable as the danger of introducing subtle issues is probably greater than its gain. In that case may recommendation would be to only generate a (bold) warning, explaining how it could be replaced but then let it run its course.

There is a debate on whether or not that bold warning should stop processing (so that the user need to press return to continue) or that it should be only a screen warning that flashes by. Personally, I think for material that really needs weeding out and would best be replaced, making a stop is better than just issuing a warning (as most people will not see a warning or even if they see will not care if it is just a warning). But as I said this is being hotly debated. Recently I wanted to introduce an error into inputenc in case of badly wrong input (that could result in wrong output without any information to the user) and many people objected, because the stop would also happen in a few cases where the input was technically wrong but the output not affected ... so in summary best practice may be seen as "ensure that user support for existing documents is not (badly) affected by your approach".

Answer 2

It would be very rude to all the users who rely on your package to swap its function for an error message. I can not understand how someone ever could consider such a reckless approach. Some years ago the maintainer of Linux Libertine cut the support for pdftex and I found myself in the middle of my work towards a deadline trying desperately to get the backup running -- after wasting precious time to investigate, why all of a sudden my file did not compile!

What you are asking is not to "retire" your package, but you don't want to maintain it any longer.

Dear package author, thank you very much for your package and for maintaining it years and years. What's left to do is to mark it as "unmaintained" in the manual and make a last update to CTAN.