Open Stack

Excerpts from Ronald Bradford's message of 2016-03-02 13:40:42 -0500:
> 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).

Would "changed" hold a list of changes, to provide a history? Or would
it just describe the difference since the last release?

> * Any new options get the "released" attribute.

And that would be set to the version in which the new attribute was
added? Maybe "added_in" is a better name?

> * 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.

Amen.

Doug

> * 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.
> 
> [1]
> http://git.openstack.org/cgit/openstack/oslo.config/tree/oslo_config/cfg.py#n636