How to deprecate bits of your program

August 31, 2009

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).

Comments on this page:

From at 2009-09-02 12:56:10:

As another example of how not to do it, consider gcc, the Gnu C compiler.

It has an option '-I-' which does various interesting things to the way that locations for included files are calculated, which is essential in more advanced build environments. Typically these environments have an idea of a "reference" set of files and you only get copies of files you are going to alter.

A person decided that '-I-' was too cryptic (although I believe that Sun altered their compiler to add support for the same feature under the same name) and introduced '-iquote' instead. However this does not have the same effect. Various fixes have been suggested over the years on the mailing list, but none have made them into the mainline code. A straight forward request to undo the deprecation and remove the "if" statement that produces the warning and an associated change in the documentation seems to be too big a change for them to make.

The net effect is that (a) I can not use the '-Werror' flag to convert warnings into hard errors, and (b) for every compile I run I get a line 'cc1: note: obsolete option -I- used, please use -iquote instead' outputted.

However they do follow your advice in that they are not quick to make it an error, this bug has existed in the datbase for at least 3 major revisions now.

Icarus Sparry

Written on 31 August 2009.
« The IO scheduler improvements I saw
Environment variables make bad switches »

Page tools: View Source, View Normal, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Aug 31 22:26:55 2009
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.