Re: [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

[Morgan Fainberg]

On Wed, May 25, 2016 at 2:48 AM, Erno Kuvaja  wrote:

> On Tue, May 24, 2016 at 8:58 PM, John Garbutt 
> wrote:
>
>> On 24 May 2016 at 19:03, Ian Cordasco  wrote:
>> > -Original Message-
>> > From: Erno Kuvaja 
>> > Reply: OpenStack Development Mailing List (not for usage questions)
>> > 
>> > Date: May 24, 2016 at 06:06:14
>> > To: OpenStack Development Mailing List (not for usage questions)
>> > 
>> > 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.
>>
>> +1
>>
>> The feedback at operator sessions in Manchester and Austin seemed to
>> back up the need for better descriptions.
>>
>>
> I'm all for _better_ descriptions.
>
>
>> More precisely, Operators should not need to read the code to
>> understand how to use the configuration option.
>>
>> Now often that means they are longer. But they shouldn't be too long.
>>
>>
> Let me give an example of what I see as a clutter with the newly proposed
> help texts:
>
> Glance config files are split per service. So we have files
> glance-api.conf, glance-registry.conf, glance-scrubber.conf etc.
> We should not need to add 300 lines (once for each option) to
> glance-api.conf containing repetitive:
> """
>
> Services which consume this:
> * ``glance-api``
> """
> As it's glance-api.conf this _should_ be self-explanatory. This is getting
> worse for certain options we have in multiple config files that will have:
> """
>
> Services which consume this:
> * ``glance-api`` (mandatory for v1; optional for v2)
> * ``image scrubber`` (a periodic task)
> * ``cache prefetcher`` (a periodic task)
> """
> Which is kind of correct, but as all these three services has their own
> configs, changing it in one does not necessarily affect the rest
> (glance-api.conf is exception here if it is available and -scrubber and/or
> -cache configs are not). So now adding these lines to glance-scrubber.conf
> gives impression that glance-api consumes it from there, which is false.
>
> Will all options in [keystone_authtoken] have a list of every single
> OpenStack service consuming it? I certainly hope not.
>
> The next part of cluttering is adding again extra ~300 redundant lines:
> """
>
> Possible values:
> * A valid port number
> """
> This is specific example for PortOpt, Currently the configgenrator
> provides following from single line help text:
> """
> # Port the registry server is listening on. (port value)
> # Minimum value: 0
> # Maximum value: 65535
> #registry_port = 9191
> """
> Is "Possible values:\n A valid port number" by any means adding value to
> that help? I've seen the same with IntOpt where configgenerator adds that
> (integer value) and we add "Possible values:\n Valid Integer".
>
> > 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 

Re: [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

[Erno Kuvaja]

On Tue, May 24, 2016 at 8:58 PM, John Garbutt  wrote:

> On 24 May 2016 at 19:03, Ian Cordasco  wrote:
> > -Original Message-
> > From: Erno Kuvaja 
> > Reply: OpenStack Development Mailing List (not for usage questions)
> > 
> > Date: May 24, 2016 at 06:06:14
> > To: OpenStack Development Mailing List (not for usage questions)
> > 
> > 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.
>
> +1
>
> The feedback at operator sessions in Manchester and Austin seemed to
> back up the need for better descriptions.
>
>
I'm all for _better_ descriptions.


> More precisely, Operators should not need to read the code to
> understand how to use the configuration option.
>
> Now often that means they are longer. But they shouldn't be too long.
>
>
Let me give an example of what I see as a clutter with the newly proposed
help texts:

Glance config files are split per service. So we have files
glance-api.conf, glance-registry.conf, glance-scrubber.conf etc.
We should not need to add 300 lines (once for each option) to
glance-api.conf containing repetitive:
"""

Services which consume this:
* ``glance-api``
"""
As it's glance-api.conf this _should_ be self-explanatory. This is getting
worse for certain options we have in multiple config files that will have:
"""

Services which consume this:
* ``glance-api`` (mandatory for v1; optional for v2)
* ``image scrubber`` (a periodic task)
* ``cache prefetcher`` (a periodic task)
"""
Which is kind of correct, but as all these three services has their own
configs, changing it in one does not necessarily affect the rest
(glance-api.conf is exception here if it is available and -scrubber and/or
-cache configs are not). So now adding these lines to glance-scrubber.conf
gives impression that glance-api consumes it from there, which is false.

Will all options in [keystone_authtoken] have a list of every single
OpenStack service consuming it? I certainly hope not.

The next part of cluttering is adding again extra ~300 redundant lines:
"""

Possible values:
* A valid port number
"""
This is specific example for PortOpt, Currently the configgenrator provides
following from single line help text:
"""
# Port the registry server is listening on. (port value)
# Minimum value: 0
# Maximum value: 65535
#registry_port = 9191
"""
Is "Possible values:\n A valid port number" by any means adding value to
that help? I've seen the same with IntOpt where configgenerator adds that
(integer value) and we add "Possible values:\n Valid Integer".

> 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 

Re: [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

[John Garbutt]

On 24 May 2016 at 19:03, Ian Cordasco  wrote:
> -Original Message-
> From: Erno Kuvaja 
> Reply: OpenStack Development Mailing List (not for usage questions)
> 
> Date: May 24, 2016 at 06:06:14
> To: OpenStack Development Mailing List (not for usage questions)
> 
> 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.

+1

The feedback at operator sessions in Manchester and Austin seemed to
back up the need for better descriptions.

More precisely, Operators should not need to read the code to
understand how to use the configuration option.

Now often that means they are longer. But they shouldn't be too long.

> 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.

Different modes of the config generator should help us cater for
multiple use cases.

I am leaving that as a discussion in oslo specs for the moment.

> 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.

Now I have been discussing a change in Nova's approach to reduce the
size of some of them, but that was really for different reasons:
http://lists.openstack.org/pipermail/openstack-dev/2016-May/095538.html

Thanks,
johnthetubaguy

__
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

Re: [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

[Hemanth Makkapati]

+1 to what Ian said.

We had an Ops session at the Austin summit on this and we didn't hear any 
concerns about the clutter from what I can recall.
Some notes from that session are here [0].
May be the clutter is not a problem after all? At least, not yet.

If it does become a problem down the line, we can probably move the 
descriptions around or have ways to not generate them at all like Ian 
suggested. 
But, keeping the help texts themselves short and compact won't solve anything. 
It is, in fact, against what we are trying to solve for here, I think.

-Hemanth

[0] https://etherpad.openstack.org/p/AUS-ops-Config-Options

From: Ian Cordasco <sigmaviru...@gmail.com>
Sent: Tuesday, May 24, 2016 1:03 PM
To: Erno Kuvaja; OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [all][oslo_config] Improving Config Option Help
Texts

-Original Message-
From: Erno Kuvaja <ekuv...@redhat.com>
Reply: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@lists.openstack.org>
Date: May 24, 2016 at 06:06:14
To: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@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

__
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

__
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

Re: [openstack-dev] [all][oslo_config] Improving Config Option Help Texts

[Ian Cordasco]

-Original Message-
From: Erno Kuvaja 
Reply: OpenStack Development Mailing List (not for usage questions)

Date: May 24, 2016 at 06:06:14
To: OpenStack Development Mailing List (not for usage questions)

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

__
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