Reformat template.rst.

Change the layout of this file to move the formatting examples to the bottom
to move clearly highlight the operator requirements section at the top. Also
update the test infrastructure to reflect the changes, and also only run
unit tests on the kilo specs.

Change-Id: Ie5e0c2779e69585c1800d6ecaf9062f3d2d81cbb
changes/57/124157/1
Kyle Mestery 8 years ago
parent 3355f24018
commit 8a524f54c7
  1. 48
      specs/skeleton.rst
  2. 270
      specs/template.rst
  3. 32
      tests/test_titles.py

@ -9,35 +9,31 @@ Title of your blueprint
==========================================
Problem description
Problem Description
===================
Proposed change
Proposed Change
===============
Alternatives
------------
Data model impact
Data Model Impact
-----------------
REST API impact
REST API Impact
---------------
Security impact
Security Impact
---------------
Notifications impact
Notifications Impact
--------------------
Other end user impact
Other End User Impact
---------------------
@ -45,14 +41,22 @@ Performance Impact
------------------
Other deployer impact
Other Deployer Impact
---------------------
Developer impact
Developer Impact
----------------
Community Impact
----------------
Alternatives
------------
Implementation
==============
@ -71,10 +75,28 @@ Dependencies
Testing
=======
Tempest Tests
-------------
Functional Tests
----------------
API Tests
---------
Documentation Impact
====================
User Documentation
------------------
Developer Documentation
-----------------------
References
==========

@ -13,115 +13,21 @@ Include the URL of your launchpad blueprint:
https://blueprints.launchpad.net/neutron/+spec/example
Introduction paragraph -- why are we doing anything? A single paragraph of
prose that operators can understand.
prose that **operators, deployers, and developers** can understand.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 80 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/neutron/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox, or see:
http://rst.ninjs.org
* If you would like to provide a diagram with your spec, text representations
are preferred. http://asciiflow.com/ is a very nice tool to assist with
making ascii diagrams. blockdiag is another tool. These are described below.
If you require an image (screenshot) for your BP, attaching that to the BP
and checking it in is also accepted. However, text representations are prefered.
* Diagram examples
asciiflow::
+----------+ +-----------+ +----------+
| A | | B | | C |
| +-----+ +--------+ |
+----------+ +-----------+ +----------+
blockdiag
.. blockdiag::
blockdiag sample {
a -> b -> c;
}
actdiag
.. actdiag::
actdiag {
write -> convert -> image
lane user {
label = "User"
write [label = "Writing reST"];
image [label = "Get diagram IMAGE"];
}
lane actdiag {
convert [label = "Convert reST to Image"];
}
}
nwdiag
.. nwdiag::
nwdiag {
network dmz {
address = "210.x.x.x/24"
web01 [address = "210.x.x.1"];
web02 [address = "210.x.x.2"];
}
network internal {
address = "172.x.x.x/24";
web01 [address = "172.x.x.1"];
web02 [address = "172.x.x.2"];
db01;
db02;
}
}
seqdiag
.. seqdiag::
seqdiag {
browser -> webserver [label = "GET /index.html"];
browser <-- webserver;
browser -> webserver [label = "POST /blog/comment"];
webserver -> database [label = "INSERT comment"];
webserver <-- database;
browser <-- webserver;
}
Problem description
Problem Description
===================
A detailed description of the problem:
* For a new feature this might be use cases. Ensure you are clear about the
* For a new feature this should be use cases. Ensure you are clear about the
actors in each use case: End User vs Deployer
* For a major reworking of something existing it would describe the
problems in that feature that are being addressed.
Proposed change
Proposed Change
===============
Here is where you cover the change you propose to make in detail. How do you
@ -130,14 +36,7 @@ propose to solve this problem?
If this is one part of a larger effort make it clear where this piece ends. In
other words, what's the scope of this effort?
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Data model impact
Data Model Impact
-----------------
Changes which require modifications to the data model often have a wider impact
@ -156,7 +55,7 @@ Questions which need to be addressed by this section include:
need to take into account existing instances, or modify other existing data
describe how that will work.
REST API impact
REST API Impact
---------------
For each API resource to be implemented using Neutron's attribute map
@ -237,7 +136,7 @@ additionaProperties should be False).
Reuse of existing predefined parameter types such as regexps for
passwords and user defined names is highly encouraged.
Security impact
Security Impact
---------------
Describe any potential security impact on the system. Some of the items to
@ -266,13 +165,13 @@ guidelines are a work in progress and are designed to help you identify
security best practices. For further information, feel free to reach out
to the OpenStack Security Group at openstack-security@lists.openstack.org.
Notifications impact
Notifications Impact
--------------------
Please specify any changes to notifications. Be that an extra notification,
changes to an existing notification, or removing a notification.
Other end user impact
Other End User Impact
---------------------
Aside from the API, are there other ways a user will interact with this feature?
@ -302,7 +201,7 @@ Examples of things to consider here include:
* Will the change include any locking, and if so what considerations are there on
holding the lock?
Other deployer impact
Other Deployer Impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
@ -326,7 +225,9 @@ that have not already been mentioned, such as:
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer impact
* Does this require downtime or manual intervention to apply when upgrading?
Developer Impact
----------------
Discuss things that will affect other developers working on OpenStack,
@ -335,6 +236,24 @@ such as:
* If the blueprint proposes a change to the API, discussion of how other
plugins would implement the feature is required.
Community Impact
----------------
Describe how this change fits in with the direction the Neutron community is
going.
* Has the change been discussed on mailing lists, at the weekly Neutron
meeting, or at a Design Summit?
* Does the change fit with the direction of the Neutron community?
Alternatives
------------
What other ways could we do this thing? Why aren't we using those? This doesn't
have to be a full literature review, but it should demonstrate that thought has
been put into why the proposed solution is an appropriate one.
Implementation
==============
@ -389,6 +308,26 @@ Is this untestable in gate given current limitations (specific hardware /
software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Tempest Tests
-------------
List new, changed, or deleted Tempest tests in this section. If a blueprint
has been filed in the Tempest specs repository, please cross reference that
blueprint here.
Functional Tests
----------------
Please document any functional tests which this change will require. New
features will require functional tests before being allowed to be merged.
Code refactors may require functional tests.
API Tests
---------
Add changes to API tests in this section. This is required if the change is
adding, removing, or changing any API related code in Neutron.
Documentation Impact
====================
@ -397,6 +336,17 @@ What is the impact on the docs team of this change? Some changes might require
donating resources to the docs team to have the documentation updated. Don't
repeat details discussed above, but please reference them here.
User Documentation
------------------
Specify any User Documentation which needs to be changed. Reference the guides
which need updating due to this change.
Developer Documentation
-----------------------
If API changes are being made, specify the developer API documentation which
will be updated to reflect the new changes here.
References
==========
@ -414,3 +364,99 @@ references are unavailable. Examples of what you could include are:
* Related specifications as appropriate (e.g. link any vendor documentation)
* Anything else you feel it is worthwhile to refer to
NOTE: Please remove everything from here and down. This section is meant to
show examples of how to format the spec.
Some notes about using this template:
* Your spec should be in ReSTructured text, like this template.
* Please wrap text at 80 columns.
* The filename in the git repository should match the launchpad URL, for
example a URL of: https://blueprints.launchpad.net/neutron/+spec/awesome-thing
should be named awesome-thing.rst
* Please do not delete any of the sections in this template. If you have
nothing to say for a whole section, just write: None
* For help with syntax, see http://sphinx-doc.org/rest.html
* To test out your formatting, build the docs using tox, or see:
http://rst.ninjs.org
* If you would like to provide a diagram with your spec, text representations
are preferred. http://asciiflow.com/ is a very nice tool to assist with
making ascii diagrams. blockdiag is another tool. These are described below.
If you require an image (screenshot) for your BP, attaching that to the BP
and checking it in is also accepted. However, text representations are prefered.
* Diagram examples
asciiflow::
+----------+ +-----------+ +----------+
| A | | B | | C |
| +-----+ +--------+ |
+----------+ +-----------+ +----------+
blockdiag
.. blockdiag::
blockdiag sample {
a -> b -> c;
}
actdiag
.. actdiag::
actdiag {
write -> convert -> image
lane user {
label = "User"
write [label = "Writing reST"];
image [label = "Get diagram IMAGE"];
}
lane actdiag {
convert [label = "Convert reST to Image"];
}
}
nwdiag
.. nwdiag::
nwdiag {
network dmz {
address = "210.x.x.x/24"
web01 [address = "210.x.x.1"];
web02 [address = "210.x.x.2"];
}
network internal {
address = "172.x.x.x/24";
web01 [address = "172.x.x.1"];
web02 [address = "172.x.x.2"];
db01;
db02;
}
}
seqdiag
.. seqdiag::
seqdiag {
browser -> webserver [label = "GET /index.html"];
browser <-- webserver;
browser -> webserver [label = "POST /blog/comment"];
webserver -> database [label = "INSERT comment"];
webserver <-- database;
browser <-- webserver;
}

@ -52,21 +52,22 @@ class TestTitles(testtools.TestCase):
return titles
def _check_titles(self, titles):
problem = 'Problem description'
problem = 'Problem Description'
self.assertIn(problem, titles)
self.assertEqual(0, len(titles[problem]))
proposed = 'Proposed change'
proposed = 'Proposed Change'
self.assertIn(proposed, titles)
self.assertIn('Alternatives', titles[proposed])
self.assertIn('Data model impact', titles[proposed])
self.assertIn('REST API impact', titles[proposed])
self.assertIn('Security impact', titles[proposed])
self.assertIn('Notifications impact', titles[proposed])
self.assertIn('Other end user impact', titles[proposed])
self.assertIn('Data Model Impact', titles[proposed])
self.assertIn('REST API Impact', titles[proposed])
self.assertIn('Security Impact', titles[proposed])
self.assertIn('Notifications Impact', titles[proposed])
self.assertIn('Other End User Impact', titles[proposed])
self.assertIn('Performance Impact', titles[proposed])
self.assertIn('Other deployer impact', titles[proposed])
self.assertIn('Developer impact', titles[proposed])
self.assertIn('Other Deployer Impact', titles[proposed])
self.assertIn('Developer Impact', titles[proposed])
self.assertIn('Community Impact', titles[proposed])
self.assertIn('Alternatives', titles[proposed])
impl = 'Implementation'
self.assertIn(impl, titles)
@ -80,11 +81,16 @@ class TestTitles(testtools.TestCase):
testing = 'Testing'
self.assertIn(testing, titles)
self.assertEqual(0, len(titles[testing]))
self.assertIn('Tempest Tests', titles[testing])
self.assertIn('Functional Tests', titles[testing])
self.assertIn('API Tests', titles[testing])
self.assertEqual(3, len(titles[testing]))
docs = 'Documentation Impact'
self.assertIn(docs, titles)
self.assertEqual(0, len(titles[docs]))
self.assertIn('User Documentation', titles[docs])
self.assertIn('Developer Documentation', titles[docs])
self.assertEqual(2, len(titles[docs]))
refs = 'References'
self.assertIn(refs, titles)
@ -93,7 +99,7 @@ class TestTitles(testtools.TestCase):
self.assertEqual(7, len(titles))
def test_template(self):
files = glob.glob('specs/*.rst') + glob.glob('specs/*/*')
files = glob.glob('specs/*.rst') + glob.glob('specs/kilo/*')
for filename in files:
self.assertTrue(filename.endswith(".rst"),
"spec's file must uses 'rst' extension.")

Loading…
Cancel
Save