[Python-Dev] Deprecation policy

[Michael Foord]

On 28/11/2011 13:36, Petri Lehtinen wrote:
> Raymond Hettinger 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.
>>
>> That may serve a notion of tidyness or somesuch but in reality it is
>> a PITA for users making it more difficult to upgrade python versions
>> and making it more difficult to use published recipes.
> I'm strongly against breaking backwards compatiblity between minor
> versions (e.g. 3.2 and 3.3). If something is removed in this manner,
> the transition period should at least be very, very long.

We tend to see 3.2 -> 3.3 as a "major version" increment, but that's 
just Python's terminology.

Nonetheless, our usual deprecation policy has been a *minimum* of 
deprecated for two releases and removed in a third (if at all) - which 
is about five years from deprecation to removal given our normal release 
rate.

The water is muddied by Python 3, where we may deprecate something in 
Python 3.1 and remove in 3.3 (hypothetically) - but users may go 
straight from Python 2.7 to 3.3 and skip the deprecation period 
altogether... So we should be extra conservative about removals in 
Python 3 (for the moment at least).

> To me, deprecating an API means "this code will not get new features
> and possibly not even (big) fixes". It's important for the long term
> health of a project to be able to deprecate and eventually remove code
> that is no longer maintained.

The issue is that deprecated code can still be a maintenance burden. 
Keeping deprecated APIs around can require effort just to keep them 
working and may actively *prevent* other changes / improvements.

All the best,

Michael Foord


> So, I think we should have a clear and working deprecation policy, and
> Ezio's suggestion sounds good to me. There should be a clean way to
> state, in both code and documentation, that something is deprecated,
> do not use in new code. Furthermore, deprecated code should actually
> be removed when the time comes, be it Python 4.0 or something else.
>
> Petri
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
>


-- 
http://www.voidspace.org.uk/

May you do good and not evil
May you find forgiveness for yourself and forgive others
May you share freely, never taking more than you give.
-- the sqlite blessing http://www.sqlite.org/different.html