How to deprecate bits of your program

Since this appears necessary, here is how to deprecate some bit of your program in a way that makes sysadmins hate you as little as possible.

• first, add a warning to your documentation and a 'compatibility switch' that causes your program to use the old behavior that you are deprecating. Of course, the compatibility switch currently does nothing since the old behavior is the current behavior, but now you've let people start explicitly specifying that they need the old behavior.

  If you are changing the behavior of your program (instead of just stopping supporting something), you should also add a switch that enables the new behavior.

(If you are not planning on having a compatibility switch at all, you lose. Flag days make sysadmins hate you with a burning hate, because there is nothing we love quite as much as having to update all sorts of other programs the moment we upgrade an OS.)

• wait until this new version of your program makes it into many or all of the popular Linux distributions and any other OS that it's commonly used on. This is not just things like Ubuntu and Fedora and Debian; you really need to wait for the long term supported, slow updating distributions like Ubuntu LTS, Red Hat Enterprise (or CentOS, if you prefer to think of it that way), and so on.

  (You need to consider Ubuntu LTS a different distribution than Ubuntu for this, because users of Ubuntu LTS may well not update their systems until the next LTS release comes out.)

  I tend to think that you should wait a minimum of a year no matter what, although given the update schedule of some of these distributions you're probably going to have to anyways.

• now you can release a version that prints warnings about the old behavior and suchlike. This version must have a way of specifically enabling the new behavior (if there is one as such).

• wait a distribution update cycle again.

• finally you can release a version that drops the old behavior, although you have to keep the now vestigial switch that enables the 'new' behavior (even though it now does nothing).

  (If you want to remove it, wait another update cycle. You saw that one coming.)

In less words: don't have any flag days. Always make sure that sysadmins and developers can prepare for a change ahead of time. Let them suppress warnings before warnings are printed and start using new behavior before it becomes mandatory (and then don't break the mechanism for this).