[python-committers] Deprecation Policy PEP

[Terry Reedy]

On 2/2/2016 9:54 AM, R. David Murray wrote:
> On Tue, 02 Feb 2016 15:33:58 +0200, Ezio Melotti <ezio.melotti at gmail.com> wrote:
>> On Sat, Jan 30, 2016 at 5:36 AM, Guido van Rossum <guido at python.org> wrote:
>>> Following the lead of 2.7.10 and 2.7.11 we could continue with 3.10, 3.11, etc.
>>>
>>
>> I think we should continue with 3.10, 3.11, etc.
>> Changing the major version should be done for incompatible changes,
>> and just doing it after 3.9 will probably just create confusion for
>> both users that will wonder if it's incompatible with Python 3 and for
>> things like the executable name.
>> Hopefully we won't need to jump to Python 4 for a long time.
>>
>>> I also want the 3->4 transition to feel like a non-event for most
>>> users. How we'll do that I don't know yet, but I want it to be a lot
>>> smoother than 2->3.
>
> I think Guido's point is that we shouldn't *make* incompatible changes,

A change change, as opposed to a removal change, is something like 1/2 
changing from 0 to .5, {}.keys() changing from a list to a dict_keys, 
and (the most disruptive) 'abc' and str() changing from bytes to 
unicode.  I think these were all needed, but now they are done.

The only comparable proposal I know of is changing .5 from a float to a 
decimal.  I think it would be much better to add new syntax, such as 
.5d, instead of (disruptively) changing the meaning of current syntax.

> and that the 4.0 transition should be smooth so that people learn we are
> committed to that.  This is potentially analogous to the linux
> transition from 2.x to 3.x, despite the fact that it goes against the
> rules of semantic versioning.
>
> That said, I don't view removing deprecated things as a incompatible
> change, since code that has dealt with the deprecations will run on both
> the version before (usually versions plural) and the version after the
> removal.

A major difference between change and removal is that using something 
removed immediately fails instead doing something not expected and 
likely wrong and maybe eventually failing.  Also, change in meaning 
usually makes cross version code impossible (without adding 'if old: do 
one thing; else: do another' conditionals).  Whereas, as you say above, 
replacements can be backported at least a couple of versions.

 > Whether we should do a mass removal in 4.0 (or the first post
> 2.7 release) is a question, and so far the sense I get of the community
> is that there is not even close to a consensus on that.  But it would
> give a semantic versioning meaning to the change from 3.x to 4.x,
> without actually being all that disruptive.

By my calculation, 3.9 will be the version after 2.7 is discontinued. 
If we do release a '3.9', make turning on DeprecationWarnings a bit 
easier so users can check if any packages they use might fail in 4.0 (or 
later)  After studying the -W doc entry move closely than many users are 
likely to, , I conclude that "-W default::DeprecationWarning" is the 
right command-line option.  Correct?  This example could be added to the 
doc.  Installers could offer to set PYTHONWARNINGS to 
'default::DeprecationWarning'.

For 4.0, I propose this: remove deprecated features from the main part 
of the doc, so they are not part of the Python 4.0 language.  Features 
not removed (yet) from the code would be relegated to an Appendix, '3.x 
remnants', which would start by declaring that the items therein are not 
in '4.0' and should not be used in new 4.0 code.  (The check for 4.0 
conformance would be to run with deprecation warnings on.)

Timing of actual removal could depend on ease of replacement.  For 
instance, things that can be deterministically replaced by a 'dep_fixer' 
could be removed in 4.0.  The unittest synonym removals are an examples. 
  Things with a replacement that can be suggested but might need to be 
checked might go in 4.1.  Things without a suggest replacement, that 
need a human rewrite, to be kept to 4.2.  (I am not sure how many things 
fit in the latter two categories.)

The deterministic fixes could be further categorized by when the 
replacement is available.  The fixer could take a parameter to specify 
the earliest version the code must work with.  Someone using the fixer 
today might specify that the result must work with 3.3 and later.  Five 
years from now, minimum versions would usually be higher.  The first 
version of a fixer could be included with 3.6.

-- tjr

PS.  Never removing obsolete items can eventually lead to problems.  See 
https://motherboard.vice.com/read/cern-engineers-have-to-identify-and-disconnect-9000-obsolete-cables 
for a non-programming example.