Open Stack

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.

Thoughts?