Open Stack

On Wed, May 21, 2014 at 4:37 PM, 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 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.


> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140521/e34c1a03/attachment.html>