[Python-Dev] Deprecation policy

[Ezio Melotti]

Hi,
a couple of years ago I suggested to define and document our
deprecation policy in this thread:
https://mail.python.org/pipermail/python-dev/2011-October/114199.html
I didn't receive many replies and eventually nothing was done.
Lately the same issue came up on #python-dev and Larry and Nick
suggested me to bring this up again.  Nick also suggested to document
our deprecation policy in PEP 5 (Guidelines for Language Evolution:
http://www.python.org/dev/peps/pep-0005/ ).

I'm including below the full text of the original email.

Best Regards,
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/