[Python-Dev] Deprecation policy

[Brett Cannon]

On Sat, Jan 25, 2014 at 8:29 AM, Ezio Melotti <ezio.melotti at gmail.com>wrote:

> 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.
>

The way I used PendingDeprecationWarning is that it is used until two
releases before removal. If we want to add a keyword-only parameter to
DeprecationWarning which specifies when the feature will be removed then
PendingDeprecationWarning is really not needed; 'removal' maybe? Could then
come up with a template format that's consistent when 'removal' is
specified:

  '{} is deprecated and slated for removal in {} {}'.format(str(self.args),
self.project, self.removal)  # self.project defaults to 'Python'.

Depending on how fancy we get we could have it so that when you warn on a
DeprecationWarning where 'removal' equals sys.version (or whatever) then it
always turns into an error case and thus raised as an exception.

-Brett


>
> 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/
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> https://mail.python.org/mailman/options/python-dev/brett%40python.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140125/df298bd8/attachment.html>