[Twisted-Python] [RFC] Deprecation Policy
jml at mumak.net
Mon Apr 28 03:36:00 EDT 2008
On Mon, Apr 28, 2008 at 4:50 PM, <glyph at divmod.com> wrote:
> On 18 Apr, 05:06 am, jml at mumak.net wrote:
> > Hello everyone,
> > Now that the release is out, 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
> 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 &
> 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).
> *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.
More information about the Twisted-Python