Open Stack

----- Original Message -----
> From: "Anne Gentle" <anne at openstack.org>
> To: openstack-docs at lists.openstack.org
> Sent: Thursday, February 20, 2014 10:59:43 AM
> Subject: [Openstack-docs] Install Guide
> 
> There's a docs group working on the Icehouse install instructions, and
> they're working towards simplifying for easier maintenance. One idea they
> came up with is manually editing the config files for all distros (Ubuntu,
> RHEL, Debian, etc.) but then also including an appendix for debconf and
> openstack-config instructions.

Hi Anne,

My preference for using tools like openstack-config in documentation (where available) is based on the fact that they explicitly tell the user where in the file (by group) a setting goes and restrict themselves to exactly what's changing. I find this is generally easier to grok than prose attempting to describe where the setting should go in the file or presenting the reader with configuration snippets and expecting them to determine where to make the change, and exactly which bits are changing. It's also easier to standardize upon a usage pattern for describing/illustrating configuration changes across a version of the guide.

> As you know, maintenance is tough with all the conditionals in the guide,
> so we wanted to see if we're okay with manual edits in the main portion,
> but moving ch_debconf.xml to an appendix and referring to it throughout. We
> can also have a RHEL/RDO appendix or openstack-config appendix.

What's the breakdown on the number of OS conditionals we lose by doing this vs the number we have to keep anyway because of discrepancies in service names, file locations, and other distribution specific details? While I suspect there are still some maintenance wins here I'm not on face value convinced without analysis that this is a significant saving, unless the proposal is to drop the OS conditionals entirely which I am staunchly against.

On face value the biggest complication here is that Ubuntu doesn't ship openstack-config, so manual instructions are still required there, I notice in the package database they do ship crudini though which is I think what openstack-config links to under the covers anyway. Perhaps we can s/openstack-config/crudini/ and then use the same instructions for Ubuntu, RHEL, CentOS, and Fedora for setting configuration keys (other than the differences I note in the previous paragraph that will still exist). The question for Thomas would then be how appropriate this is on Debian?

> Seems like the model makes for easier maintenance while also pushing the
> "learning by doing" aspect of that guide.

I don't see a significant difference here, given in both cases the user is really manually setting each configuration key - just using a CLI tool instead of an editor. Not sure if debconf streamlines this further than openstack-config does? I think enhancing the learning aspect would involve being more descriptive of what each change is actually doing - something that is lacking in places - rather than modifying the way it is set (either way works the same).

Thanks,

Steve