On Mon, Apr 28, 2008 at 4:50 PM,
On 18 Apr, 05:06 am, jml@mumak.net wrote:
Hello everyone,
Now that the release is out[1], I'd like to start work on fixing #1216 -- official deprecation policy.
Sorry for the delay. Due to a miscommunication, I thought that Chris would be the one writing up our meeting notes and announcing this. After I realized I was the one who was supposed to be doing it, I wanted to write up something official-sounding on the wiki first, but of course, there's never enough time. So here's a rough cut at the policy that we (the current "TSF board", such as it is: chris, me, JP, and itamar) agreed on at the sprint in Cambridge.
Thanks, Jonathan, for motivating this; we've needed a clear statement for a long time. Someone (and this will probably be me) needs to make a complete and unambiguous index of official Twisted policy and put it together somewhere, probably on the wiki, at least at first.
I'm glad I could help and I'm glad that this is being worked on. Although I'm happy to leave the decision in your hands, there are a couple of things I'd like to comment on (disagree with). Also, I'd be happy to start the work of collating policy.
- Is it time-based or release-based?
Both. There will be a minimum amount of time and a minimum number of releases before a deprecated feature may be removed.
I dislike this. I think that deprecations should be release-based and that we should commit to time-based releases. I think this is simpler for users and for developers. This complaint would be largely solved by automation.
- How long for?
Every deprecation must last for a minimum of 2 releases and a minimum of one year. Of course, anyone who wants to keep maintaining deprecated APIs for longer than that may do so.
Presumably the timer starts at a release and only increments at a release? So, for example: T - 1 month: deprecate feature in trunk T: Release N T + 7 months: Release N+1 T + 14 months: Release N+2, feature removed. Is this understanding correct? (The fact that I need to ask is largely why I don't like "both time & release based".)
I know this is somewhat longer than you've suggested, but at the meeting we ran down a laundry list of real-world usages of Twisted and pretty much nobody upgrades Twisted more than once per year.
I think the data on this is skewed, since there was about a 1.4 year gap between the last 2 releases of Twisted. If we released each month, I can imagine this would change. Nevertheless, I'm content with this sort of time frame for now, as long as the support for it is well automated.
The idea behind using PendingDeprecationWarning is that *users* of a piece of software which depends on Twisted should, in principle, be able to upgrade Twisted by one version without seeing any error output.
I think that this is a nice feature, but not worth breaking our backs over. (It might be really easy to do though).
However, *maintainers* of that software should immediately see all the warnings when they test with a new release. Trial should change to show all PendingDeprecationWarnings by default. However, this might be impractical due to other uses of PendingDeprecationWarning - if that is the case, Twisted should include its own warning class. It may be helpful to do that in order to include the additional metadata required for an automated deprecation workflow, however. The desired deprecation workflow is:
* Twisted developer deprecates functionality, by adding a warnings.warn(TwistedDeprecationWarning(some useful metadata)) to the code.
I disagree very strongly on this detail. The deprecation API should be higher level than that. Specifically, even we implement it with the warnings system, I don't think we should litter that decision all over our code base.
An obvious remaining piece of work to implement this final policy is to define some temporary manual things that we can do until such a tool is implemented, and implement the tool itself as soon as possible. I don't believe any tickets have yet been filed for this, and *that* I am leaving in our venerable release manager's court, since this is all a part of the release process except for the fairly minor change to trial.
I think this is wasted effort. Let's just build the damn tool.
- Which code is subject to this policy?
All Python code released in Twisted, with the exceptions of private modules and test modules.
What about code currently marked as deprecated?
There's obviously some work to do here to make this policy easy and convenient to follow. This needs to be edited, CompatibilityPolicy updated, and prominently linked. We need someone to write up at least two different summaries: one for maintainers of projects using Twisted ("What kind of compatibility should I expect from Twisted releases?") one for Twisted contributors ("How do I add a deprecation? When can I remove it?") and maybe one for users and one for packagers, too. We need some tools to help us update deprecations. We need trial to change so that developers are notified earlier than their users.
Do I hear any volunteers...? :)
Me. I wouldn't have raised the issue if I wasn't willing. jml