[openstack-dev] [all] Base feature deprecation policy

Sean Dague sean at dague.net
Tue Sep 8 12:13:14 UTC 2015


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.

	-Sean

-- 
Sean Dague
http://dague.net



More information about the OpenStack-dev mailing list