[Python-Dev] When to remove deprecated stuff

[Ezio Melotti]

On Thu, Aug 22, 2013 at 7:45 PM, Donald Stufft <donald at stufft.io> wrote:
>
> On Aug 22, 2013, at 1:34 PM, Ezio Melotti <ezio.melotti at gmail.com> wrote:
>
>> Hi,
>>
>> On Thu, Aug 22, 2013 at 1:00 PM, Petri Lehtinen <petri at digip.org> wrote:
>>>
>>> Removing some cruft on each release can be very painful for users.
>>>
>>> Django's deprecation policy works like this: They deprecate something
>>> in version A.B. It still works normally in A.B+1, generates a
>>> (silenced) DeprecationWarning in A.B+2, and is finally removed in
>>> A.B+3.
>>
>> I see two problems with this:
>> 1) DeprecationWarnings should be generated as soon as the feature is
>> deprecated (i.e. A.B, not A.B+2).  Holding off the warnings is not
>> helping anyone.
>> 2) The deprecation period seems fixed and independent from the
>> feature.  IMHO the period should vary depending on what is being
>> deprecated.  Little known/used "features" could be deprecated in A.B
>> and removed in A.B+1; common "features" can be deprecated in A.B and
>> removed in A.B+n, with an n >= 2 (or even wait for A+1).
>
> This isn't exactly accurate, it raises a PendingDeprecation warning in A.B,
> Deprecation in A.B+1, and removed in A.B+2.
>
> PendingDeprecation (In Django) was designed to be silent by default
> and Deprecation loud by default. That got messed up when Python
> silenced Deprecation warnings by default and we've had to resort to
> some ugliness to restore that behavior.
>

So it's not much different from what we do now, except that we
basically stopped using PendingDeprecationWarning ->
DeprecationWarning and just use DeprecationWarnings from the
beginning.

I don't see many advantages in keeping the pending deprecation
warnings silent for developers, as it just encourages procrastination
:)
One advantage is that under your scheme, one can assume that what
shows up as deprecated (not pending deprecated) will be removed in the
next version, so you could focus your work on them first, but this
doesn't work for our scheme were a deprecated "feature" might stay
there for a couple of versions.

Maybe we should introduce a ``.removed_in`` attribute to
DeprecationWarnings?  We some times mention it in the deprecation
message and the docs, but there's no way to get that information
programmatically.

Best Regards,
Ezio Melotti

>>
>>> So if I haven't read through the full release notes of each
>>> release nor enabled DeprecationWarnings, I end up having something
>>> broken each time I upgrade Django.
>>>
>>
>> Reading the release notes shouldn't be required -- DeprecationWarnings
>> are already supposed to tell you what to change.
>> If you have good test coverage this should happen automatically (at
>> least with unittest), but even if you don't you should run your code
>> with -Wa before upgrading (or test your code on the new version before
>> upgrading Python/Django/etc. in production).
>>
>> Best Regards,
>> Ezio Melotti
>>
>>> I hope the same will not start happening each time I upgrade Python.
>>> When the removals happen on major version boundaries, it should be
>>> more evident that something will break. Then people can enable
>>> DepreationWarnings and test all the affected code thoroughly with the
>>> new version before upgrading.
>>>
>>> Petri
>> _______________________________________________
>> Python-Dev mailing list
>> Python-Dev at python.org
>> http://mail.python.org/mailman/listinfo/python-dev
>> Unsubscribe: http://mail.python.org/mailman/options/python-dev/donald%40stufft.io
>
>
> -----------------
> Donald Stufft
> PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA
>