[openstack-dev] [Oslo] Improving deprecated options identification and documentation

Doug Hellmann doug at doughellmann.com
Thu Jan 14 18:25:47 UTC 2016


Excerpts from Jay Pipes's message of 2016-01-14 11:58:13 -0500:
> On 01/14/2016 11:45 AM, Ronald Bradford wrote:
> > Presently the oslo.config Opt class has the attributes
> > deprecated_for_removal and deprecated_reason [1]
> >
> > I would like to propose that we use deprecated_reason (at a minimum) to
> > detail in what release an option was deprecated in, and what release it
> > is then removed in.
> 
> You mean what release it *will* be removed in, right? Clearly, once it's 
> removed, there won't be any indication it ever existed ;)
>
> > I see examples of deprecated_for_removal=True but no information on why
> > or when.  i.e. Ideally I'd like to move to an implied situation of
> >   if deprecated_for_removal=True then deprecated_reason is mandatory.
> 
> +1

+1

> 
> > A great example is an already documented help message in oslo.log
> > configuration option use_syslog_rfc_format that at least provides a
> > guideline.  [2] shows a proposed review to take this low road approach.
> > An image of what the change actually looks like in documentation using
> > this approach [3].  This also needs  #267151 that fixes an issue where
> > deprecated options are not producing a warning message in docs.
> >
> > The high road would be to have a discussion about if there is a better
> > way to mark and manage deprecated options. For example, if there was a
> > deprecated_release and a removal_release attribute then a level of
> > tooling could make this easier.  I would be wary in considering this, as
> > it adds complexity (is it needed), and just how many options are
> > deprecated.  I'd appreciate thoughts and feedback.
> 
> Any improvement in this regard I think would enhance the user experience 
> considerably, thank you Ronald for tackling this area. I'd also suggest 
> cc'ing (or sending a separate ML post) to the openstack-operators@ ML to 
> gather feedback from ops folks.

Good idea.

Maybe we could generate a warning when deprecated_for_removal is
True instead of a string? Then when the value is a string we could use
it as part of the deprecation warning when the option is being set in a
deployment.

Doug

> 
> Best,
> -jay
> 



More information about the OpenStack-dev mailing list