Open Stack

On 21/05/14 22:56, James Slagle wrote:
> 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.

You can blame me for that, when I created the repository I took the nova
template and removed the sections I thought we're not relevant perhaps I
was a little too aggressive. I got no problem if we want to add any of
them back in.

Looks like these are the sections I removed:
Data model impact
REST API impact
Notifications impact

I'd obviously forgotten about Tuskar, sorry.


> 
> Anyway, just my $0.02.
>