Allow short-specs

* Clarify the template to describe the requirements and process for
  submitting initial drafts better.
* Add testing for a specs/backlog dir which allows "short specs"
  to be accepted in that dir even if they are missing some sections.
* Add a sample file to the specs/backlog dir, for demonstration.
* Update the index page

Change-Id: I634635467f5cbe565958dbcd360399bc5f0b96ec

doc/source/index.rst

@@ -4,15 +4,18 @@
 Ironic Project Specifications
 =============================
 
-Juno approved specs:
+This serves as a reference for approved specs within the current, and each
+prior, release cycle. At the end of a cycle, specs which were approved but not
+implemented at all will be deleted and should be re-proposed. Specs which were
+partly implemented will be modified to indicate such, and a continuation spec
+should be proposed for the new cycle. Additionally, a "backlog" of ideas is
+maintained to indicate the agreed-upon goals for the project which have no
+specific work being done on them at this time.
 
-.. toctree::
-   :glob:
-   :maxdepth: 1
+Current cycle: 'Kilo'
+=====================
 
-   specs/juno/*
-
-Kilo approved specs:
+Approved specs:
 
 .. toctree::
    :glob:
@@ -20,6 +23,27 @@ Kilo approved specs:
 
    specs/kilo/*
 
+Idea back-log:
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/backlog/*
+
+
+Previous cycles
+===============
+
+Specs completed during 'Juno':
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/juno/*
+
+
 ==================
 Indices and tables
 ==================

specs/backlog/example.rst

@@ -0,0 +1,25 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==========================================
+This is a sample to test rendering only
+==========================================
+
+This is only a sample. It tests the rendering of templates in the backlog.
+
+Problem description
+===================
+
+There is not a clear way for reviewers to know that short specs are being
+rendered properly without a sample.
+
+This sample can be deleted once any real spec file is added to the backlog
+dir. Or, alternately, it can remain here.
+
+Proposed change
+===============
+
+Add this sample. That's all that needs to be done.

specs/template.rst

@@ -50,6 +50,22 @@ Some notes about using this template:
 
   https://review.openstack.org/#/q/status:open+project:openstack/ironic-specs+message:apiimpact,n,z
 
+* If you are unsure whether this proposal is aligned with the project's
+  mission and scope, you are encouraged to submit a minimal spec to get
+  feedback early, before investing the effort in a complete specification.
+  Do this by filling in the `Problem description` and `Proposed change`
+  sections and delete the rest of the template. This will fail unit tests,
+  but will still get attention from the review team.
+
+* If you do not wish to submit a complete spec (for example, you do not plan
+  to complete the spec during this cycle but would like to document the idea)
+  you can submit a short spec. It must contain at least the `Problem
+  description` and `Proposed change` sections, and may optionally contain any
+  other valid sections. Propose this to the `specs/backlog` directory. This
+  must follow all other rules of a regular spec (eg, it still requires a
+  blueprint, good RST formatting, etc).
+
+
 Problem description
 ===================
 
@@ -72,8 +88,7 @@ If this is one part of a larger effort make it clear where this piece ends.
 In other words, what is the scope of this effort?
 
 If you are unsure whether this proposal is aligned with the project's mission
-and scope, stop here and get feedback from the ironic-drivers and ironic-core
-teams before fleshing out all the details below.
+and scope, stop here.
 
 Alternatives
 ------------

tests/test_titles.py

@@ -19,6 +19,12 @@ import testtools
 
 RELEASE = 'kilo'
 
+DRAFT_DIR = 'backlog'
+DRAFT_REQUIRED_TITLES = {
+        'Problem description': [],
+        'Proposed change': [],
+        }
+
 
 class TestTitles(testtools.TestCase):
     def _get_title(self, section_tree):
@@ -41,9 +47,10 @@ class TestTitles(testtools.TestCase):
                 titles[section['name']] = section['subtitles']
         return titles
 
-    def _check_titles(self, filename, expect, actual):
+    def _check_titles(self, filename, expect, allowed, actual):
         missing_sections = [x for x in expect.keys() if x not in actual.keys()]
-        extra_sections = [x for x in actual.keys() if x not in expect.keys()]
+        extra_sections = [x for x in actual.keys() if x not in
+                dict(expect.items() + allowed.items())]
 
         msgs = []
         if len(missing_sections) > 0:
@@ -85,23 +92,47 @@ class TestTitles(testtools.TestCase):
             self.assertEqual(len(trailing_spaces),0,
                     "Found trailing spaces on line %s of %s" % (i+1, tpl))
 
-    def test_template(self):
+    def _check_file_ext(self, filename):
+        self.assertTrue(filename.endswith(".rst"),
+                        "spec's file must uses 'rst' extension.")
+
+    def _get_spec_titles(self, filename):
+        with open(filename) as f:
+            data = f.read()
+
+        spec = docutils.core.publish_doctree(data)
+        titles = self._get_titles(spec)
+        return (data, titles)
+
+    def _get_template_titles(self):
         with open("specs/template.rst") as f:
             template = f.read()
         spec = docutils.core.publish_doctree(template)
         template_titles = self._get_titles(spec)
+        return template_titles
 
+    def test_current_cycle_template(self):
+        template_titles = self._get_template_titles()
         files = glob.glob('specs/%s/*' % RELEASE)
 
         for filename in files:
-            self.assertTrue(filename.endswith(".rst"),
-                            "spec's file must uses 'rst' extension.")
-            with open(filename) as f:
-                data = f.read()
+            self._check_file_ext(filename)
 
-            spec = docutils.core.publish_doctree(data)
-            titles = self._get_titles(spec)
-            self._check_titles(filename, template_titles, titles)
+            (data, titles) = self._get_spec_titles(filename)
+            self._check_titles(filename, template_titles, {}, titles)
+            self._check_lines_wrapping(filename, data)
+            self._check_no_cr(filename, data)
+            self._check_trailing_spaces(filename, data)
+
+    def test_backlog(self):
+        template_titles = self._get_template_titles()
+        files = glob.glob('specs/%s/*' % DRAFT_DIR)
+
+        for filename in files:
+            self._check_file_ext(filename)
+            (data, titles) = self._get_spec_titles(filename)
+            self._check_titles(filename, DRAFT_REQUIRED_TITLES,
+                                template_titles, titles)
             self._check_lines_wrapping(filename, data)
             self._check_no_cr(filename, data)
             self._check_trailing_spaces(filename, data)