On 21/05/14 22:56, James Slagle wrote: > 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.
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. > _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
