Open Stack

Merging a few of the replies into a single response:

 > I like all of this plan, except for the name "Overview". To me, 
"Overview" suggests a high-level summary rather than being "one of the 
beefier sections of a spec". Something like "Detail" or "Detailed 
overview" (because the low-level detail will come in the changes that 
implement the spec, not in the spec) seem like better descriptions of 
what we intend to have there.

I didn't put much thought into the name, so Overview, Summary, Detail, 
etc. doesn't matter to me. If we agree to go down the route of a holder 
section here (as compared to loosening the validation), I'll poll for a 
better name.

>> 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 ^^^).

That's actually my expectation, that everything currently in place gets 
slapped under Overview. The change is pretty much only to support being 
able to further break down that section while still leaving the existing 
level of validation in place. It's not so much organizational as it is 
to make sphinx happy.

>> 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 agree that it's possible I'll be back here in the next few days 
complaining that my problem description is too large and would benefit 
from subsections, which I couldn't currently add because they'd be 
second-level sections which are strictly enforced.

>> 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.


 > We just landed a change to permit the third level subsections, but the
intent AIUI of requiring exact titles to constrain the expression
space in the interests of clarity. We can (and should) add more
standard sections as needed.

I do like the idea of having these look consistent. I can work within 
the structure fine given that third-level subsections are permitted, but 
my issue is still that I have been treating the first section under 
"Proposed Change" as the meaty part of the change, which due to the lack 
of a second-level subsection doesn't let me add my own subsections.


Given the feedback, there are a few approaches we can take:

1. Add a second-level subsection at the start of Proposed Change. This 
subsection will be the description of the actual change and adding in 
this will allow custom subsections to be permitted by the existing unit 
tests.

2. Reduce the validation to only enforce required sections but not barf 
on the addition of new ones.


Somewhat tangential (but to address Slagle's concern) is the question of 
whether or not we need some sort of template version number to prevent 
having to update X many existing specs when changing the structure in 
the future. I feel like this is overkill and it's probably much simpler 
to settle on a Juno template in the very near future (selfishly, I say 
"near" to allow my own issue here to be addressed) and then only change 
the templates at new versions. Again, I'm probably overthinking things 
at this point, but just throwing it out there.


Personally, my vote is for #1. Existing specs are simple to update, just 
slap the existing change under the new subsection and move on. For the 
naming of it, I'm fine with James P's suggestion of "Detail".

Then for K, we make any changes to the template based on our usage of it 
in Juno. It's like a scrum post mortem task for a giant 6 month sprint :)