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 :)
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
