[Twisted-Python] [RFC] Deprecation Policy

[Itamar Shtull-Trauring]

> 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).

Of course! This wasn't meant to be a dictate.

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

The hope is that this will be the effective end result. But our release
process is not *yet* (though it is the goal) completely automated, so
having fall back position of minimum time is handy. Also, what happens
if we decide to switch to more (or less frequent releases)?


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

I think so.

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

At ITA we've been using 2.4 for quite a while... though someone recently
switched us to 2.5.

> >   * 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.

I agree. We actually talked about high level API at the meeting,
possibly glyph forgot, disagrees, or just took inaccurate notes :)