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

Ronald Bradford me at ronaldbradford.com
Thu Mar 3 14:54:16 UTC 2016

> > * 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?
I would consider "changed" as last release the option has changed, so that
effectively for a given current release did the option change in that
release, or not.  An option could change in multiple releases, and would be
indicated as such during each release cycle.

I do not see this feature providing specifics such as "Option X changed
default value from False to True".  It would be that in a section "Changed
Options" there is a list of options marked as changed. The use of comparing
generated configuration files between releases as used now would determine
specifics.  The goal here is to narrow down the time to do the work across
many projects and projects with many options.

> > * 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?
> Yes, added or first_added 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160303/0f22cbd8/attachment.html>

More information about the OpenStack-dev mailing list