Ronald Bradford <m...@ronaldbradford.com> wrote on 03/02/2016 07:40:42 PM:
> From: Ronald Bradford <m...@ronaldbradford.com> > To: "OpenStack Development Mailing List (not for usage questions)" > <openstack-dev@lists.openstack.org> > Date: 03/02/2016 07:41 PM > Subject: [openstack-dev] [oslo][all] Documenting configuration options lifespan > > 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. > > [1] http://git.openstack.org/cgit/openstack/oslo.config/tree/ > oslo_config/cfg.py#n636 Right now I have trouble to paint a picture in my head how this will look like in the end. Could you provide a mockup of the resulting artifact? I also don't fully understand how the ops would work with that artifact. Could you describe an example workflow? We use the reno files in Nova to document deprecations of config options and changes to them which are relevant for upgrades [1]. How does this differ to your proposal? References: [1] http://docs.openstack.org/releasenotes/nova/unreleased.html Regards, Markus Zoeller (markus_z) __________________________________________________________________________ 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
