Open Stack

We just landed a change to permit the third level subsections, but the
intent AIUI of requiring exact titles to constrain the expression
space in the interests of clarity. We can (and should) add more
standard sections as needed.

-Rob

On 22 May 2014 08:37, Jay Dobies <jason.dobies at 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.
>
> Thoughts?
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 
Robert Collins <rbtcollins at hp.com>
Distinguished Technologist
HP Converged Cloud