[python-committers] Deprecation Policy PEP

[Serhiy Storchaka]

On 29.01.16 19:11, Ezio Melotti wrote:
> Deprecation Warnings
> ====================
>
> Python offers two kinds of deprecation warnings:
>
> * ``PendingDeprecationWarning``
> * ``DeprecationWarning``
>
> Initially, only ``PendingDeprecationWarning``\ s were silenced by
> default.  Starting from Python 2.7, ``DeprecationWarning``\ s
> are also silenced by default [#]_ [#]_.
>
> Since this distinction is no longer true:
>
> * ``PendingDeprecationWarning`` should not be used
> * ``DeprecationWarning`` will be used for all deprecations
>
> ``PendingDeprecationWarning`` won't be removed, and 3rd-party
> projects are allowed to use it as they see fit.

What about adding deprecations in bugfix releases? If current behavior 
is obviously incorrect and should be fixed in development branch, but 
this can break existing code that implicitly depends on current 
behavior. Can we add documentation-only warnings or use 
PendingDeprecationWarning if possible?

> Deprecation Process
> ===================
>
> These are the steps required to deprecate and remove an API:
>
> 1. propose to deprecate an API on a tracker issue or on python-dev
>     and decide in which version it will be removed.
>
> 2. attach to the issue a patch to deprecate the API that:
>
>    * adds a ``DeprecationWarning`` to the code

Some deprecation can be documentation-only.

May be worth to mention also ``FutureWarning``. AFAIK it is used if the 
method will not be removed in future, but it's behavior will be changed 
in incompatible way.

>    * adds the deprecation to the documentation

Needed explicit link to the "Documenting the deprecations" section.

>    * adds a test to verify that the warning is raised
>    * possibly updates code/examples that uses the deprecated API
>
> 3. after review, apply the patch to the current in-development
>     branch and close the issue.
>
> 4. attach to a separate issue a patch to remove the API that:
>
>    * removes the API and the warning
>    * removes the tests for the API and for the deprecation
>    * removes the API documentation
>
> 5. once the designated branch is available, apply the patch and
>     close the issue.

There is a special case for pickling. Existing pickle data created in 
old Python releases can contain references to deprecated classes or 
factory functions. Either we should keep old names (even non-public) as 
aliases to new names or add new mapping for 3 to 3 translation in 
_compat_pickle.py or new module.

> Documenting the deprecations
> ============================
>
> * All deprecations should be documented in the docs, using the
>    ``deprecated-removed`` directive.

When use ``deprecated`` and when use ``deprecated-removed``?