On Wed, May 21, 2014 at 4:37 PM, Jay Dobies <jason.dob...@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@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
