[Python-Dev] Deprecation policy

[Ezio Melotti]

Hi,
our current deprecation policy is not so well defined (see e.g. [0]), 
and it seems to me that it's something like:
   1) deprecate something and add a DeprecationWarning;
   2) forget about it after a while;
   3) wait a few versions until someone notices it;
   4) actually remove it;

I suggest to follow the following process:
   1) deprecate something and add a DeprecationWarning;
   2) decide how long the deprecation should last;
   3) use the deprecated-remove[1] directive to document it;
   4) add a test that fails after the update so that we remember to 
remove it[2];

Other related issues:

PendingDeprecationWarnings:
* AFAIK the difference between PDW and DW is that PDW are silenced by 
default;
* now DW are silence by default too, so there are no differences;
* I therefore suggest we stop using it, but we can leave it around[3] 
(other projects might be using it for something different);

Deprecation Progression:
Before, we more or less used to deprecated in release X and remove in 
X+1, or add a PDW in X, DW in X+1, and remove it in X+2.
I suggest we drop this scheme and just use DW until X+N, where N is >=1 
and depends on what is being removed.  We can decide to leave the DW for 
2-3 versions before removing something widely used, or just deprecate in 
X and remove in X+1 for things that are less used.

Porting from 2.x to 3.x:
Some people will update directly from 2.7 to 3.2 or even later versions 
(3.3, 3.4, ...), without going through earlier 3.x versions.
If something is deprecated on 3.2 but not in 2.7 and then is removed in 
3.3, people updating from 2.7 to 3.3 won't see any warning, and this 
will make the porting even more difficult.
I suggest that:
   * nothing that is available and not deprecated in 2.7, will be 
removed until 3.x (x needs to be defined);
   * possibly we start backporting warnings to 2.7 so that they are 
visible while running with -3;

Documenting the deprecations:
In order to advertise the deprecations, they should be documented:
   * in their doc, using the deprecated-removed directive (and possibly 
not the 'deprecated' one);
   * in the what's new, possibly listing everything that is currently 
deprecated, and when it will be removed;
Django seems to do something similar[4].
(Another thing I would like is a different rending for deprecated 
functions.  Some part of the docs have a deprecation warning on the top 
of the section and the single functions look normal if you miss that.  
Also while linking to a deprecated function it would be nice to have it 
rendered with a different color or something similar.)

Testing the deprecations:
Tests that fail when a new release is made and the version number is 
bumped should be added to make sure we don't forget to remove it.
The test should have a related issue with a patch to remove the 
deprecated function and the test.
Setting the priority of the issue to release blocker or deferred blocker 
can be done in addition/instead, but that works well only when N == 1 
(the priority could be updated for every release though).
The tests could be marked with an expected failure to give some time 
after the release to remove them.
All the deprecation-related tests might be added to the same file, or 
left in the test file of their module.

Where to add this:
Once we agree about the process we should write it down somewhere.
Possible candidates are:
   * PEP387: Backwards Compatibility Policy[5] (it has a few lines about 
this);
   * a new PEP;
   * the devguide;
I think having it in a PEP would be good, the devguide can then link to it.


Best Regards,
Ezio Melotti


[0]: http://bugs.python.org/issue13248
[1]: deprecated-removed doesn't seem to be documented in the documenting 
doc, but it was added here: http://hg.python.org/cpython/rev/03296316a892
[2]: see e.g. 
http://hg.python.org/cpython/file/default/Lib/unittest/test/test_case.py#l1187
[3]: we could also introduce a MetaDeprecationWarning and make 
PendingDeprecationWarning inherit from it so that it can be used to 
pending-deprecate itself.  Once PendingDeprecationWarning is gone, the 
MetaDeprecationWarning will become useless and can then be used to 
meta-deprecate itself.
[4]: https://docs.djangoproject.com/en/dev/internals/deprecation/
[5]: http://www.python.org/dev/peps/pep-0387/