[Twisted-Python] [RFC] Deprecation Policy

[Jonathan Lange]

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[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