Open Stack

On 05/10/2016 06:36 PM, Ronald Bradford wrote:
> Andreas,
> 
> I would advocate for NOT moving flagmappings files to individual project
> repositories.   Having worked out recently how configuration tables are
> generated and was able to generate them myself I considered how to
> improve the process in relation to using the existing oslo.config
> generation tools.

the idea here is to move this to the creation of the options. So,
instead of a flagmappings file, it would be part of each configuration -
and thus whenever a new change gets added, the config table value would
be added as well.

> 
> The primary reason for not moving the flagmappings file is you are then
> dependent on the projects review cycle (and processes) to get these
> changes approved.  This includes the load on the gate, and applicable +2
> by cores (which on major projects have their own priorities for
> features) etc.  I would not like to see documentation generation data
> dependent on all applicable projects.

I agree - that's why it should be change itself that adds these.

> I see the bigger issue is the current process for generating the config
> guides including the frequency and accuracy during the cycle.
> 
> In a nutshell, it's a huge pull process, where at some time somebody
> runs the tools which pulls in all projects, and dependencies and uses a
> doc specific version to identify all the config options, merge with
> flagmappings and produce configuration tables.

And the way forward would be to have oslo.config generate this
automatically for us.

Let's see what Doug and KATO come up with.

> Ideally, a more optimal means is to create a push process, that is, if
> any configuration settings changes within a project during a commit,
> this data change is pushed, so that the documentation can be updated
> accordingly when applicable.  Nice in theory, in practice it's more
> complex. Some high level thoughts on the process.
> 
> Some projects now can generate a sample configuration file (tox
> -egenconfig).  In Oslo we are hoping to increase this usage, and use the

And we just want to get rid of this process, Doug worked on a way to
include the sample configs as part of documentation builds.

> developer docs as a place to store these files within a project repo.
> Leveraging this existing functionality, if we could detect a change in
> the sample configuration file during a review commit, then we have the
> notification process (keystone already has a bot that does this) that is
> the basic information trigger of a new change needed in docs for config.
> Now, what is that change of configuration is more complex, and it would
> seem a logical necessity to use a neutral format (e.g. yaml) to record
> the parsed configuration options, and enable this format to be saved
> somewhere/somehow.  This becomes both the input to the oslo.config
> generator (i.e. we effectively take current functionality and split it
> into two parts, the parsing of configuration options into yaml format,
> and the generation of sample config files, and developer docs sphinx
> extensions using the yaml format. The yaml data also forms the basis of
> data for the configuration guide.   
> One may argue why break up the oslo.config work because it's working,
> well because the inputs are used to generate multiple forms of
> documentation and at present only some forms are being used.
> 
> I am certainly not familiar with the infra work for bots, and how within
> a gate to create, propose and commit work of a produced yaml file, or
> change in yaml file.
> 
> It does seem like this could be a lot of work, but it's the foundation
> of converging the work the documentation team does with tools that exist
> for the development side, as well as reducing the tool complexity that
> exists in doc tools now.


thanks for the comments. Let's see what Doug and KATO will work out.

I would rather use oslo.config to generate RST tables to include than
the current process. Using oslo.config the same way that projects run
tox -egenconfig today, I hope that Config Ref generation becomes easier,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126