<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, May 24, 2016 at 8:58 PM, John Garbutt <span dir="ltr"><<a href="mailto:john@johngarbutt.com" target="_blank">john@johngarbutt.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div class=""><div class="h5">On 24 May 2016 at 19:03, Ian Cordasco <<a href="mailto:sigmavirus24@gmail.com">sigmavirus24@gmail.com</a>> wrote:<br>
> -----Original Message-----<br>
> From: Erno Kuvaja <<a href="mailto:ekuvaja@redhat.com">ekuvaja@redhat.com</a>><br>
> Reply: OpenStack Development Mailing List (not for usage questions)<br>
> <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
> Date: May 24, 2016 at 06:06:14<br>
> To: OpenStack Development Mailing List (not for usage questions)<br>
> <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
> Subject:  [openstack-dev] [all][oslo_config] Improving Config Option Help Texts<br>
><br>
>> Hi all,<br>
>><br>
>> Based on the not yet merged spec of categorized config options [0] some<br>
>> project seems to have started improving the config option help texts. This<br>
>> is great but I noticed scary trend on clutter to be added on these<br>
>> sections. Now looking individual changes it does not look that bad at all<br>
>> in the code 20 lines well structured templating. Until you start comparing<br>
>> it to the example config files. Lots of this data is redundant to what is<br>
>> generated to the example configs already and then the maths struck me.<br>
>><br>
>> In Glance only we have ~120 config options (this does not include<br>
>> glance_store nor any other dependencies we pull in for our configs like<br>
>> Keystone auth. Those +20 lines of templating just became over 2000 lines of<br>
>> clutter in the example configs and if all projects does that we can<br>
>> multiply the issue. I think no-one with good intention can say that it's<br>
>> beneficial for our deployers and admins who are already struggling with the<br>
>> configs.<br>
>><br>
>> So I beg you when you do these changes to the config option help fields<br>
>> keep them short and compact. We have the Configuration Docs for extended<br>
>> descriptions and cutely formatted repetitive fields, but lets keep those<br>
>> off from the generated (Example) config files. At least I would like to be<br>
>> able to fit more than 3 options on the screen at the time when reading<br>
>> configs.<br>
>><br>
>> [0] <a href="https://review.openstack.org/#/c/295543/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/295543/</a><br>
><br>
> Hey Erno,<br>
><br>
> So here's where I have to very strongly disagree with you. That spec<br>
> was caused by operator feedback, specifically for projects that<br>
> provide multiple services that may or may not have separated config<br>
> files which and which already have "short and compact" descriptions<br>
> that are not very helpful to oeprators.<br>
<br>
</div></div>+1<br>
<br>
The feedback at operator sessions in Manchester and Austin seemed to<br>
back up the need for better descriptions.<br>
<br></blockquote><div><br></div><div>I'm all for _better_ descriptions.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
More precisely, Operators should not need to read the code to<br>
understand how to use the configuration option.<br>
<br>
Now often that means they are longer. But they shouldn't be too long.<br>
<span class=""><br></span></blockquote><div><br></div><div>Let me give an example of what I see as a clutter with the newly proposed help texts:</div><div><br></div><div>Glance config files are split per service. So we have files glance-api.conf, glance-registry.conf, glance-scrubber.conf etc.</div><div>We should not need to add 300 lines (once for each option) to glance-api.conf containing repetitive:</div><div>"""</div><div><div><div><br></div><div>Services which consume this:</div><div>    * ``glance-api``</div></div></div><div>""" </div><div>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:<br></div><div>"""</div><div><div><br></div><div>Services which consume this:</div><div>    * ``glance-api`` (mandatory for v1; optional for v2)</div><div>    * ``image scrubber`` (a periodic task)</div><div>    * ``cache prefetcher`` (a periodic task)</div></div><div>"""</div><div>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.</div><div><br></div><div>Will all options in [keystone_authtoken] have a list of every single OpenStack service consuming it? I certainly hope not.</div><div><br></div><div>The next part of cluttering is adding again extra ~300 redundant lines:</div><div>"""</div><div><div><br></div><div>Possible values:</div><div>    * A valid port number</div></div><div>"""</div><div>This is specific example for PortOpt, Currently the configgenrator provides following from single line help text:</div><div>"""</div><div><div># Port the registry server is listening on. (port value)</div><div># Minimum value: 0</div><div># Maximum value: 65535</div><div>#registry_port = 9191</div></div><div>"""</div><div>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".</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><span class="">
> The *example* config files will have a lot more detail in them. Last I<br>
> saw (I've stopped driving that specification) there was going to be a<br>
> way to generate config files without all of the descriptions. That<br>
> means that for operators who don't care about that can ignore it when<br>
> they generate configuration files. Maybe the functionality doesn't<br>
> work right this instant, but I do believe that's a goal and it will be<br>
> implemented.<br>
<br>
</span>Different modes of the config generator should help us cater for<br>
multiple use cases.<br>
<br></blockquote><div><br></div><div>I'm not asking to strip it all off. I'm asking us not to clutter the example config files with redundant or confusing data just because of the sake of it. More is not necessarily better.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">
I am leaving that as a discussion in oslo specs for the moment.<br>
<span class=""><br>
> Beyond that, I don't think example/sample configuration files should<br>
> be treated differently from documentation, nor do I think that our<br>
> documentation team couldn't make use of the improved documentation<br>
> we're adding to each option. In short, I think this effort will<br>
> benefit many different groups of people in and around OpenStack.<br>
> Simply arguing that this is going to make the sample config files have<br>
> more lines of code is not a good argument against this. Please do<br>
> reconsider.<br>
<br></span></blockquote><div><br></div><div>So sorry if I got misunderstood. Hopefully the above explained what I'm against of.</div><div><br></div><div>Best,</div><div>Erno "jokke_" Kuvaja</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><span class="">
</span>Now I have been discussing a change in Nova's approach to reduce the<br>
size of some of them, but that was really for different reasons:<br>
<a href="http://lists.openstack.org/pipermail/openstack-dev/2016-May/095538.html" rel="noreferrer" target="_blank">http://lists.openstack.org/pipermail/openstack-dev/2016-May/095538.html</a><br>
<br>
Thanks,<br>
johnthetubaguy<br>
</blockquote></div><br></div></div>