[python-committers] Deprecation Policy PEP

[Ezio Melotti]

On Fri, Jan 29, 2016 at 8:00 PM, Serhiy Storchaka <storchaka at gmail.com> wrote:
> 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?
>

Usually deprecations are added in minor releases -- I don't know if we
added DeprecationWarnings in bugfix releases before.  Adding
documentation-only warnings in previous releases shouldn't be a
problem.  We already did this in the 2.7 docs for APIs that have been
deprecated/renamed/removed in 3.x.
If for example we deprecate something in 3.6, I see no harm in adding
a doc warning to the 2.7/3.5 docs stating that the feature is
deprecated starting from 3.6 and removed in 3.8.
I don't think we need to add DWs/PWDs though.

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

Do you have examples where this has been done?
I don't see the point of telling doc readers that a feature is
deprecated but keeping the same information hidden to developers.  If
the actual warnings cause some issue, then the issue should be
addresses (the issue of being noisy has already been addressed by
silencing them by default), but having doc-only deprecation warnings
seems inconsistent and potentially confusing.

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

Good point. I'll investigate a bit and add it.

>>    * adds the deprecation to the documentation
>
>
> Needed explicit link to the "Documenting the deprecations" section.
>

OK.

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

If I understand correctly, this only affects pickleable APIs that have
been moved/renamed.
You could argue that if we are willing to break code that uses the old
names, then we could do the same to old pickles.  Keeping the names
around will allow both code and pickles to keep working and we will
effectively have an indefinite deprecation without removal.  If it can
be done in a _compat_pickle.py it might be ok.

This is also another issue that I forgot to mention -- I would like to
always set a version where the API will be removed, but sometimes this
might mean Python 4.
(FTR the reason is not to "clean up" the language ASAP, but to provide
a clear timeline for both the API users and the core-devs.  This is
also based on the assumption that no deprecated code will stay around
forever; even if it's not remove in the immediate future, at some
point it will.)

Do you think it's fine using Python 4, or is it better to have
indefinite (for some value of indefinite) deprecations?
(Do we also expect to have 3.10, 3.11, etc. after 3.9, or will we just
move to 4.0 even though we might not have major incompatible changes?)

Regardless of the decision, I want the documentation to actually match
the code, so as long as the code is there and it is deprecated, the
doc should say that it is there and it is deprecated.  If the API is
deprecated indefinitely, the docs should say so (and possibly say why
too).

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

If we agree to always specify when the API will be removed, then we
won't need to use "deprecated" anymore.
If we want to keep using indefinite deprecations we will use it for them.

This should be specified in the PEP once we reach a consensus.


Best Regards,
Ezio Melotti