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.