Open Stack

Excerpts from Dan Prince's message of 2015-04-13 14:07:28 -0700:
> On Tue, 2015-04-07 at 21:06 +0000, Gregory Haynes wrote:
> > Hello,
> > 
> > Id like to propse a standard for consistently documenting our
> > diskimage-builder elements. I have pushed a review which transforms the
> > apt-sources element to this format[1][2]. Essentially, id like to move
> > in the direction of making all our element README.rst's contain a sub
> > section called Environment Vairables with a Definition List[3] where
> > each entry is the environment variable. Under that environment variable
> > we will have a field list[4] with Required, Default, Description, and
> > optionally Example.
> > 
> > The goal here is that rather than users being presented with a wall of
> > text that they need to dig through to remember the name of a variable,
> > there is a quick way for them to get the information they need. It also
> > should help us to remember to document the vital bits of information for
> > each vairable we use.
> > 
> > Thoughts?
> 
> I like the direction of the cleanup. +2
> 
> I do wonder who we'll enforce consistency in making sure future changes
> adhere to the new format. It would be nice to have a CI check on these
> things so people don't constantly need to debate the correct syntax,
> etc.

I agree Dan, which is why I'd like to make sure these are machine
readable and consistent. I think it would actually make sense to make
our argument isolation efforts utilize this format, as that would make
sure that these are consistent with the code as well.