From 5e8571e1c1f1459d11d03dc475deddc0bab90dce Mon Sep 17 00:00:00 2001 From: Fawad Khaliq Date: Thu, 5 Nov 2015 00:52:21 -0800 Subject: [PATCH] Add specs directory to Kuryr As the Kuryr community is increasing, a more structured approach towards blueprints will be very helpful. So added the specs directoty with a skeleton and a template. Change-Id: I8d1ee2c2d76a0d1b82eb5dd5963b33bfb31f5b9d --- doc/source/index.rst | 8 +++++ doc/source/specs/index.rst | 44 ++++++++++++++++++++++++ doc/source/specs/skeleton.rst | 23 +++++++++++++ doc/source/specs/template.rst | 64 +++++++++++++++++++++++++++++++++++ 4 files changed, 139 insertions(+) create mode 100644 doc/source/specs/index.rst create mode 100644 doc/source/specs/skeleton.rst create mode 100644 doc/source/specs/template.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 758d192b..18c7b672 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -25,6 +25,14 @@ Design and Developer Docs devref/index +Kuryr Specs +=========== + +.. toctree:: + :maxdepth: 1 + + specs/index + Indices and tables ================== diff --git a/doc/source/specs/index.rst b/doc/source/specs/index.rst new file mode 100644 index 00000000..2d23e6a9 --- /dev/null +++ b/doc/source/specs/index.rst @@ -0,0 +1,44 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels: + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + (Avoid deeper levels because they do not render well.) + + +Kuryr Specs +=========== + +This section contains detailed specification documents for +different features inside Kuryr. + + +Spec Template +-------------- +.. toctree:: + :maxdepth: 3 + + skeleton + template + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/specs/skeleton.rst b/doc/source/specs/skeleton.rst new file mode 100644 index 00000000..7ffc364d --- /dev/null +++ b/doc/source/specs/skeleton.rst @@ -0,0 +1,23 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Title of your RFE +========================================== + + +Problem Description +=================== + + +Proposed Change +=============== + + +References +========== + + diff --git a/doc/source/specs/template.rst b/doc/source/specs/template.rst new file mode 100644 index 00000000..521e8d7a --- /dev/null +++ b/doc/source/specs/template.rst @@ -0,0 +1,64 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================== +Example Spec - The title of your RFE +==================================== + +Include the URL of your launchpad RFE: + +https://bugs.launchpad.net/kuryr/+bug/example-id + +Introduction paragraph -- why are we doing this feature? A single paragraph of +prose that **deployers, and developers, and operators** can understand. + +Do you even need to file a spec? Most features can be done by filing an RFE bug +and moving on with life. In most cases, filing an RFE and documenting your +design is sufficient. If the feature seems very large or contentious, then +you may want to consider filing a spec. + + +Problem Description +=================== + +A detailed description of the problem: + +* 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. + +Note that the RFE filed for this feature will have a description already. This +section is not meant to simply duplicate that; you can simply refer to that +description if it is sufficient, and use this space to capture changes to +the description based on bug comments or feedback on the spec. + + +Proposed Change +=============== + +How do you propose to solve this problem? + +This section is optional, and provides an area to discuss your high-level +design at the same time as use cases, if desired. Note that by high-level, +we mean the "view from orbit" rough cut at how things will happen. + +This section should 'scope' the effort from a feature standpoint: how is the +'kuryr end-to-end system' going to look like after this change? What Kuryr +areas do you intend to touch and how do you intend to work on them? The list +below is not meant to be a template to fill in, but rather a jumpstart on the +sorts of areas to consider in your proposed change description. + +You do not need to detail API or data model changes. + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable.