[Python-Dev] Deprecation policy

[Xavier Morel]

On 2011-11-28, at 10:30 , Raymond Hettinger wrote:
> On Oct 24, 2011, at 5:58 AM, Ezio Melotti wrote:
> How about we agree that actually removing things is usually bad for users.
> It will be best if the core devs had a strong aversion to removal.
> Instead, it is best to mark APIs as obsolete with a recommendation to use something else instead.
> There is rarely a need to actually remove support for something in the standard library.
The problem with "deprecating and not removing" (and worse, only informally deprecating by leaving a note in the documentation) is that you end up with zombie APIs: there are tons of tutorials & such on the web talking about them, they're not maintained, nobody really cares about them (but users who found them via Google) and they're all around harmful.

It's the current state of many JDK 1.0 and 1.1 APIs and it's dreadful, most of them are more than a decade out of date, sometimes retrofitted for new interfaces (but APIs using them usually are *not* fixed, keeping them in their state of partial death), sometimes still *taught*, all of that because they're only informally deprecated (at best, sometimes not even that as other APIs still depend on them). It's bad for (language) users because they use outdated and partially unmaintained (at least in that it's not improved) APIs and it's bad for (language) maintainers in that once in a while they still have to dive into those things and fix bugs cropping up without the better understanding they have from the old APIs or the cleaner codebase they got from it.

Not being too eager to kill APIs is good, but giving rise to this kind of living-dead APIs is no better in my opinion, even more so since Python has lost one of the few tools it had to manage them (as DeprecationWarning was silenced by default). Both choices are harmful to users, but in the long run I do think zombie APIs are worse.