Open Stack

On Wed, May 21, 2014 at 4:37 PM, Jay Dobies <jason.dobies at redhat.com> wrote:
> Currently, there is the following in the template:
>
>
>
> Proposed change
> ===============
>
> [snip]
>
> Alternatives
> ------------
>
> [snip]
>
> Security impact
> ---------------
>
>
>
> The unit tests assert the top and second level sections are standard, so if
> I add a section at the same level as Alternatives under Proposed Change, the
> tests will fail. If I add a third level section using ^, they pass.
>
> The problem is that you can't add a ^ section under Proposed Change. Sphinx
> complains about a title level inconsistency since I'm skipping the second
> level and jumping to the third. But I can't add a second-level section
> directly under Proposed Change because it will break the unit tests that
> validate the structure.
>
> The proposed change is going to be one of the beefier sections of a spec, so
> not being able to subdivide it is going to make the documentation messy and
> removes the ability to link directly to a portion of a proposed change.
>
> I propose we add a section at the top of Proposed Change called Overview
> that will hold the change itself. That will allow us to use third level
> sections in the change itself while still having the first and section
> section structure validated by the tests.
>
> I have no problem making the change to the templates, unit tests, and any
> existing specs (I don't think we have any yet), but before I go through
> that, I wanted to make sure there wasn't a major disagreement.
>

I'm a bit ambivalent to be honest, but adding a section for Overview
doesn't really do much IMO.  Just give an overview in the first couple
of sentences under "Proposed Change". If I go back and add an Overview
section to my spec in review, I'm just going to slap everything in
Proposed Change into one Overview section :).  To me, Work Items is
where more of the details goes (which does support aribtrary
subsections with ^^^).

In general though I think that the unit tests are too rigid and
pedantic. Plus, having to go back and update old specs when we make
changes to unit tests seems strange. No biggie right now, but we do
have a couple of specs in review. Unless we write the unit tests to be
backwards compatible. This just feels a bit like engineering just for
the sake of it.  Maybe we need a spec on it :).

I was a bit surprised to see that we don't have the Data Model section
in our specs, and when I had one, unit tests failed. We actually do
have data model stuff in Tuskar and our json structures in tripleo.

Anyway, just my $0.02.

-- 
-- James Slagle
--