[openstack-dev] [Oslo] Improving deprecated options identification and documentation
me at ronaldbradford.com
Thu Jan 14 16:45:47 UTC 2016
Presently the oslo.config Opt class has the attributes
deprecated_for_removal and deprecated_reason 
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.
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.
A great example is an already documented help message in oslo.log
configuration option use_syslog_rfc_format that at least provides a
guideline.  shows a proposed review to take this low road approach.
An image of what the change actually looks like in documentation using this
approach . 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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev