<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, May 21, 2014 at 4:37 PM, Jay Dobies <span dir="ltr"><<a href="mailto:jason.dobies@redhat.com" target="_blank">jason.dobies@redhat.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Currently, there is the following in the template:<br>
<br>
<br>
<br>
Proposed change<br>
===============<br>
<br>
[snip]<br>
<br>
Alternatives<br>
------------<br>
<br>
[snip]<br>
<br>
Security impact<br>
---------------<br>
<br>
<br>
<br>
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.<br>


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


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


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

</blockquote><div><br></div><div>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.</div>

<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
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.<br>


<br>
Thoughts?<br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</blockquote></div><br></div></div>