Open Stack

-----Original Message-----
From: Erno Kuvaja <ekuvaja at redhat.com>
Reply: OpenStack Development Mailing List (not for usage questions)
<openstack-dev at lists.openstack.org>
Date: May 24, 2016 at 06:06:14
To: OpenStack Development Mailing List (not for usage questions)
<openstack-dev at lists.openstack.org>
Subject:  [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

> Hi all,
>
> Based on the not yet merged spec of categorized config options [0] some
> project seems to have started improving the config option help texts. This
> is great but I noticed scary trend on clutter to be added on these
> sections. Now looking individual changes it does not look that bad at all
> in the code 20 lines well structured templating. Until you start comparing
> it to the example config files. Lots of this data is redundant to what is
> generated to the example configs already and then the maths struck me.
>
> In Glance only we have ~120 config options (this does not include
> glance_store nor any other dependencies we pull in for our configs like
> Keystone auth. Those +20 lines of templating just became over 2000 lines of
> clutter in the example configs and if all projects does that we can
> multiply the issue. I think no-one with good intention can say that it's
> beneficial for our deployers and admins who are already struggling with the
> configs.
>
> So I beg you when you do these changes to the config option help fields
> keep them short and compact. We have the Configuration Docs for extended
> descriptions and cutely formatted repetitive fields, but lets keep those
> off from the generated (Example) config files. At least I would like to be
> able to fit more than 3 options on the screen at the time when reading
> configs.
>
> [0] https://review.openstack.org/#/c/295543/

Hey Erno,

So here's where I have to very strongly disagree with you. That spec
was caused by operator feedback, specifically for projects that
provide multiple services that may or may not have separated config
files which and which already have "short and compact" descriptions
that are not very helpful to oeprators.

The *example* config files will have a lot more detail in them. Last I
saw (I've stopped driving that specification) there was going to be a
way to generate config files without all of the descriptions. That
means that for operators who don't care about that can ignore it when
they generate configuration files. Maybe the functionality doesn't
work right this instant, but I do believe that's a goal and it will be
implemented.

Beyond that, I don't think example/sample configuration files should
be treated differently from documentation, nor do I think that our
documentation team couldn't make use of the improved documentation
we're adding to each option. In short, I think this effort will
benefit many different groups of people in and around OpenStack.
Simply arguing that this is going to make the sample config files have
more lines of code is not a good argument against this. Please do
reconsider.

--
Ian Cordasco