[Twisted-Python] [RFC] Deprecation Policy

[Jonathan Lange]

Hello everyone,

Now that the release is out[1], I'd like to start work on fixing #1216
-- official deprecation policy.

There's one proposed policy at
http://twistedmatrix.com/trac/wiki/CompatibilityPolicy, there's also
one mentioned in the ticket itself: deprecate in release N, remove in
release N+1. Glyph has at one point expressed a desire for time-based
deprecation.[2]

I think these are all the questions we need to answer:
- Is it time-based or release-based?
- How long for?
- Do we grade deprecations? How?
- Which code is subject to this policy?

CompatibilityPolicy suggests release-based deprecation that is graded
over 4 releases: release N PendingDeprecationWarning, N+1
DeprecationWarning, N+2 DeprecationError, N+3 remove the
functionality.

Ticket #1216 suggests a release-based deprecation policy that is not
graded and over 1 release: release N, add DeprecationWarning, release
N+1, remove the functionality.

Important factors to bear in mind:
- Maintaining deprecated APIs brings a cost to developers when they
maintain code.
- Removing APIs brings a cost to users when they choose to upgrade.
- We will probably always be changing APIs and making mistakes when we
change them.


Now, here's what I think.

* Release-based, not time-based.

Releases are easy to track, dates are less so. This is as true for
Twisted programmers as it is for sysadmins & other Twisted users. I
think that whatever problems are solved by time-based deprecation are
better solved by regular releases.

Our releases should, of course, be time-based. But that's another discussion.

* Two release deprecation length.

That is: release N, DeprecationWarning; release N+1,
DeprecationWarning; release N+2, remove the functionality.

This is enough to allow users to upgrade their version of Twisted
incrementally. Trial has been doing one release for quite a while now,
and I can't recall any complaints about breaking compatibility in
released code.

Micro-releases don't count.

* No grading

I think the DeprecationWarning vs PendingDeprecationWarning vs
DeprecationError is too much hassle. Just say "next release" or "in
two releases time".

* All "public" code and command-line tools should be covered. Things
marked as deprecated at the time of the 8.0 release should be
grandfathered so as to be safe for removal.

Anything else will get too confusing. The removal of the API stability
markers agrees with this. Everything is public unless it starts with
one underscore.[3]

Most importantly, we should have a policy, we should all agree and as
much of the policy as possible should be implemented in Python. This
bug has been open for years now, and it is frustrating for the policy
to change under one's feet or to disagree with other developers on
something so fundamental. "Explicit is better than implicit".

I'm sending this now because the 8.0 release is settling down and we
have a sprint coming up where it might be easier to resolve this
quickly.

jml

[1] I'm so happy.
[2] http://twistedmatrix.com/trac/ticket/2352
[3] This hurts. t.trial.util doesn't begin with an underscore.