Open Stack

Cross posting from the openstack-dev ML.


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 [to be] 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.  [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.

Regards

Ronald


[1] http://docs.openstack.org/developer/oslo.config/opts.html
[2] https://review.openstack.org/#/c/267176/
[3] http://postimg.org/image/vdkh3x46t/full/