Open Stack

Excerpts from Sean Dague's message of 2015-09-08 08:13:14 -0400:
> On 09/03/2015 08:22 AM, Thierry Carrez wrote:
> > Hi everyone,
> > 
> > A feature deprecation policy is a standard way to communicate and
> > perform the removal of user-visible behaviors and capabilities. It helps
> > setting user expectations on how much and how long they can rely on a
> > feature being present. It gives them reassurance over the timeframe they
> > have to adapt in such cases.
> > 
> > In OpenStack we always had a feature deprecation policy that would apply
> > to "integrated projects", however it was never written down. It was
> > something like "to remove a feature, you mark it deprecated for n
> > releases, then you can remove it".
> > 
> > We don't have an "integrated release" anymore, but having a base
> > deprecation policy, and knowing which projects are mature enough to
> > follow it, is a great piece of information to communicate to our users.
> > 
> > That's why the next-tags workgroup at the Technical Committee has been
> > working to propose such a base policy as a 'tag' that project teams can
> > opt to apply to their projects when they agree to apply it to one of
> > their deliverables:
> > 
> > https://review.openstack.org/#/c/207467/
> > 
> > Before going through the last stage of this, we want to survey existing
> > projects to see which deprecation policy they currently follow, and
> > verify that our proposed base deprecation policy makes sense. The goal
> > is not to dictate something new from the top, it's to reflect what's
> > generally already applied on the field.
> > 
> > In particular, the current proposal says:
> > 
> > "At the very minimum the feature [...] should be marked deprecated (and
> > still be supported) in the next two coordinated end-of-cyle releases.
> > For example, a feature deprecated during the M development cycle should
> > still appear in the M and N releases and cannot be removed before the
> > beginning of the O development cycle."
> > 
> > That would be a n+2 deprecation policy. Some suggested that this is too
> > far-reaching, and that a n+1 deprecation policy (feature deprecated
> > during the M development cycle can't be removed before the start of the
> > N cycle) would better reflect what's being currently done. Or that
> > config options (which are user-visible things) should have n+1 as long
> > as the underlying feature (or behavior) is not removed.
> > 
> > Please let us know what makes the most sense. In particular between the
> > 3 options (but feel free to suggest something else):
> > 
> > 1. n+2 overall
> > 2. n+2 for features and capabilities, n+1 for config options
> > 3. n+1 overall
> > 
> > Thanks in advance for your input.
> 
> Based on my experience of projects in OpenStack projects in what they
> are doing today:
> 
> Configuration options are either N or N+1: either they are just changed,
> or there is a single deprecation cycle (i.e. deprecated by Milestone 3
> of release N, removed before milestone 1 of release N+1). I know a lot
> of projects continue to just change configs based on the number of
> changes we block landing with Grenade.
> 
> An N+1 policy for configuration seems sensible. N+2 ends up pretty
> burdensome because typically removing a config option means dropping a
> code path as well, and an N+2 policy means the person deprecating the
> config may very well not be the one removing the code, leading to debt
> or more bugs.
> 
> For features, this is all over the map. I've seen removes in 0 cycles
> because everyone is convinced that the feature doesn't work anyway (and
> had been broken for some amount of time). I've seen 1 cycle deprecations
> for minor features that are believed to be little used. In Nova we did
> XML deprecation over 2 cycles IIRC. EC2 is going to be 2+ (we're still
> waiting to get field data back on the alternate approach). The API
> version deprecations by lots of projects are measured in years at this
> point.
> 
> I feel like a realistic bit of compromise that won't drive everyone nuts
> would be:
> 
> config options: n+1
> minor features: n+1
> major features: at least n+2 (larger is ok)
> 
> And come up with some fuzzy words around minor / major features.
> 
> I also think that ensuring that any project that gets this tag publishes
> a list of deprecations in release notes would be really good. And that
> gets looked for going forward.

These times seem reasonable to me.

I'd like to come up with some way to express the time other than
N+M because in the middle of a cycle it can be confusing to know
what that means (if I want to deprecate something in August am I
far enough through the current cycle that it doesn't count?).

Also, as we start moving more projects to doing intermediate releases
the notion of a "release" vs. a "cycle" will drift apart, so we
want to talk about "stable releases" not just any old release.

Doug