[python-committers] Deprecation Policy PEP

[Ezio Melotti]

On Sat, Jan 30, 2016 at 4:08 AM, Martin Panter <vadmium+py at gmail.com> wrote:
>> What and when to deprecate
>> ==========================
>>
>> * The number of releases before an API is removed is decided
>>   on a case-by-case basis depending on widely used the API is
>
> depending on [how] widely used
>
>> * In general it's better to be conservative, and if the API is
>>   deprecated in ``3.X``, it shouldn't be removed before ``3.X+2``.
>>   This should also take into account which Python versions are
>>   currently .
>
> which Python versions are [current].
>
> More explicitly, I would say as a guideline, if the proposed
> alternative is unavailable in 3.Y, consider waiting until 3.Y becomes
> unsupported or unused before removing (or even fully deprecating) an
> API.
>
>> Porting from 2.x to 3.x
>> -----------------------
>>
>> In order to make porting code to 3.X easier:
>>
>> * nothing that is available and not deprecated in 2.7 should be
>>   removed from Python 3 as long as 2.7 is officially supported;
>
> What about an API not documented in Python 3, like
> http.client.HTTPMessage.getallmatchingheaders()
> <https://bugs.python.org/issue5053>? In this case I think the method
> was rendered useless in 3.0 and it is not worth fixing.
>

The goal is to avoid unnecessary breakage.  In this case the code will
need to be fixed regardless, so the best we can do is to add a -3
warning to 2.7 .

> Also I presume you mean not originally deprecated in 2.7.0. In other
> words adding a “python2 -3” warning in the next 2.7 bug fix doesn’t
> give me a license to remove an API from 3.6.
>

Yes, even if you could argue that even removing things that were
already deprecated will make porting more difficult.  Perhaps I should
rephrase the section focusing the working on making the porting
easier.

>> Deprecation Progression
>> =======================
>>
>> 1. in release ``3.X`` a ``DeprecationWarning`` is added
>> 2. in release ``3.X+N`` the API is removed
>>
>> ``N`` can be ``>=1``, should be decided beforehand, and should be
>> documented explicitly.
>
> How do we decide on the value of N for something that has to wait
> until 2.7 is dead? Just estimate based on anticipated future release
> dates? E.g. inspect.getargspec(). In some cases I think indefinite
> deprecation is better.
>

An estimation is fine.
I would use 4.0 for indefinite deprecations.  If we use the rst
directives to collect all the deprecated APIs in a single page, we can
go through them once 2.7 is dead.

>> Deprecation Process
>> ===================
>
>> 2. attach to the issue a patch to deprecate the API that:
>>
>>   * adds a ``DeprecationWarning`` to the code
>>   * adds the deprecation to the documentation
>>   * adds a test to verify that the warning is raised
>
> Often people propose a test that will detect when the version changes
> to >= X+N and complains if the API has not been removed. Should this
> be encouraged or discouraged?
>

I did it once and it ended up breaking tests in the middle of the next release.
For the sake of the release managers, I don't think it should be done,
especially if we come up with a better way to track deprecations.

>>   * possibly updates code/examples that uses the deprecated API
>
> Also adjust any tests to suppress the new warning. Code to do this
> typically looks like
>
> with warnings.catch_warnings():
>     warnings.simplefilter("ignore", DeprecationWarning)
>     deprecated.api()
>

For tests there should be a convenience function in test.support.

>> 3. after review, apply the patch to the current in-development
>>    branch and close the issue.
>
> Also apply similar changes to 2.7 if applicable?
>
>> Documenting the deprecations
>> ============================
>>
>> * All deprecations should be documented in the docs, using the
>>   ``deprecated-removed`` directive.
>
> If an undocumented API is being deprecated, you may not have to touch
> the main documentation (but still consider a notice in What’s New).