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?
_______________________________________________
OpenStack-dev mailing list
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
