[openstack-dev] [oslo][all] Documenting configuration options lifespan

Ronald Bradford me at ronaldbradford.com
Wed Mar 2 18:40:42 UTC 2016

After evaluation of oslo-config-generator and one of it's common uses by
operators in configuration option evaluation with upgrades, I am proposing
adding some meta data for all configuration options to provide better
applicable documentation as projects continue to evolve.

I can see an easier and system generated means to provide information such
as "What's New", "What's Changed", "What's Deprecated" for project
configurations in each new release, in system documentation and release
notes.  This will greatly simplify the review of newer available releases
and improve the experience of upgraded deployments.

For each configuration option I'm proposing we can identify "released",
"changed", "deprecated", "removal" release info, e.g. K,L,M,N etc.

Initial seeding of existing configuration options is that no information is
needed. i.e. no upfront investment to start.
Possible work items moving forward would include:

* When an option is changed, or marked as deprecated, during normal reviews
it should then be identified accordingly with these new attributes.
* The "changed" attribute would only be applicable moving forward with a
developer change in default value, ranges etc (changing help text or
re-ordering is not a change).
* Any new options get the "released" attribute.
* Initial work to fill in the "deprecated" and "removal" information (i.e.
for a small number of existing options per project) would add strong value
to generated documentation.
* Additional work to add the initial "released" information can be left to
an intro contributor task.  Information of an options existence in a
project can be automated via analysis of branches to provide details of the
seed info needed.

As for implementation, the use of a named tuple attribute for
oslo_config.cfg.Opt [1] is one approach.  Determining how to take advantage
of debtcollector and versionutils should be considered.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160302/3652b727/attachment.html>

More information about the OpenStack-dev mailing list