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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev