On Wed, May 21, 2014 at 4:37 PM, Jay Dobies <jason.dob...@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 -- _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
