From 2c10be4ec48f0412a5d385432c9aeb64d58ffb06 Mon Sep 17 00:00:00 2001 From: Sampath Priyankara Date: Tue, 10 Jan 2017 11:04:49 +0900 Subject: [PATCH] Add spec repo structure This patch add spec repo structure to masakari-specs. TODO: Need to add spec tests Change-Id: I171724efbd716b1f775057bfd117686c086dd09c --- .gitignore | 11 + .testr.conf | 7 + LICENSE | 3 + README.rst | 78 +++++ doc/source/conf.py | 93 +++++ doc/source/contributing.rst | 21 ++ doc/source/index.rst | 33 ++ doc/source/readme.rst | 1 + doc/source/specs/ocata/approved | 1 + doc/source/specs/ocata/implemented | 1 + doc/source/specs/ocata/index.rst | 26 ++ doc/source/specs/ocata/redirects | 1 + doc/source/specs/ocata/template.rst | 1 + doc/source/template.rst | 86 +++++ requirements.txt | 4 + setup.cfg | 24 ++ setup.py | 22 ++ specs/.gitignore | 0 specs/ocata-template.rst | 389 +++++++++++++++++++++ specs/ocata/approved/ocata-template.rst | 1 + specs/ocata/implemented/ocata-template.rst | 1 + specs/ocata/redirects | 0 template.rst | 86 +++++ test-requirements.txt | 0 tox.ini | 25 ++ 25 files changed, 915 insertions(+) create mode 100644 .gitignore create mode 100644 .testr.conf create mode 100644 LICENSE create mode 100644 README.rst create mode 100755 doc/source/conf.py create mode 100644 doc/source/contributing.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/readme.rst create mode 120000 doc/source/specs/ocata/approved create mode 120000 doc/source/specs/ocata/implemented create mode 100644 doc/source/specs/ocata/index.rst create mode 120000 doc/source/specs/ocata/redirects create mode 120000 doc/source/specs/ocata/template.rst create mode 100644 doc/source/template.rst create mode 100644 requirements.txt create mode 100644 setup.cfg create mode 100755 setup.py create mode 100644 specs/.gitignore create mode 100644 specs/ocata-template.rst create mode 120000 specs/ocata/approved/ocata-template.rst create mode 120000 specs/ocata/implemented/ocata-template.rst create mode 100644 specs/ocata/redirects create mode 100644 template.rst create mode 100644 test-requirements.txt create mode 100644 tox.ini diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..478debc --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +AUTHORS +ChangeLog +build +.tox +.venv +*.egg* +*.swp +*.swo +*.pyc +.testrepository +.DS_Store diff --git a/.testr.conf b/.testr.conf new file mode 100644 index 0000000..6d83b3c --- /dev/null +++ b/.testr.conf @@ -0,0 +1,7 @@ +[DEFAULT] +test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \ + OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \ + OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-60} \ + ${PYTHON:-python} -m subunit.run discover -t ./ . $LISTOPT $IDOPTION +test_id_option=--load-list $IDFILE +test_list_option=--list diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..75a29c4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,3 @@ +This work is licensed under a Creative Commons Attribution 3.0 Unported License. + +http://creativecommons.org/licenses/by/3.0/legalcode diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..2a09b18 --- /dev/null +++ b/README.rst @@ -0,0 +1,78 @@ +=============================== +README +=============================== + +OpenStack Masakari Specifications +============================= + + +This git repository is used to hold approved design specifications for additions +to the Masakari project. Reviews of the specs are done in gerrit, using a +similar workflow to how we review and merge changes to the code itself. + +The layout of this repository is:: + + specs// + +Where there are two sub-directories: + + specs//approved: specifications approved but not yet implemented + specs//implemented: implemented specifications + + +The lifecycle of a specification +-------------------------------- + +Developers proposing a specification should propose a new file in the +``approved`` directory. masakari-core will review the change in the usual +manner for the OpenStack project, and eventually it will get merged if a +consensus is reached. At this time the Launchpad blueprint is also approved. +The developer is then free to propose code reviews to implement their +specification. These reviews should be sure to reference the Launchpad +blueprint in their commit message for tracking purposes. + +Once all code for the feature is merged into Masakari, +the Launchpad blueprint is marked complete. +As the developer of an approved specification it is your +responsibility to mark your blueprint complete when all of the required +patches have merged. + +Periodically, someone from masakari-core will move implemented specifications +from the ``approved`` directory to the ``implemented`` directory. +Individual developers are also welcome to propose this move for their +implemented specifications. +It is important to create redirects when this is done so that +existing links to the approved specification are not broken. Redirects aren't +symbolic links, they are defined in a file which sphinx consumes. An example +is at ``specs/ocata/redirects``. + +This directory structure allows you to see what we thought about doing, +decided to do, and actually got done. Users interested in functionality in a +given release should only refer to the ``implemented`` directory. + + +Example specifications +---------------------- + +You can find an example spec in ``specs/ocata-template.rst``. + + +Working with gerrit and specification unit tests +------------------------------------------------ + +For more information about working with gerrit, see +http://docs.openstack.org/infra/manual/developers.html#development-workflow + +To validate that the specification is syntactically correct (i.e. get more +confidence in the Jenkins result), please execute the following command:: + + $ tox + +After running ``tox``, the documentation will be available for viewing in HTML +format in the ``doc/build/`` directory. + + +* Free software: Apache license +* Documentation: http://docs.openstack.org/developer/masakari-specs + +* TODO diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..ec78c6e --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,93 @@ +# -*- coding: utf-8 -*- +# 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. + +import datetime +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'oslosphinx', + 'yasfb', +] + +# Feed configuration for yasfb +feed_base_url = 'http://specs.openstack.org/openstack/masakari-specs' +feed_author = 'OpenStack Development Team' + +exclude_patterns = [ + 'template.rst', +] + +# Optionally allow the use of sphinxcontrib.spelling to verify the +# spelling of the documents. +try: + import sphinxcontrib.spelling + extensions.append('sphinxcontrib.spelling') +except ImportError: + pass + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'masakari-specs' +copyright = u'%s, OpenStack Foundation' % datetime.date.today().year + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..fd72c4a --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,21 @@ +============================================= +Contributing to: masakari-specs +============================================= + +If you would like to contribute to the development of OpenStack, you must +follow the steps in this page: + + http://docs.openstack.org/infra/manual/developers.html + +If you already have a good understanding of how the system works and your +OpenStack accounts are set up, you can skip to the development workflow +section of this documentation to learn how changes to OpenStack should be +submitted for review via the Gerrit tool: + + http://docs.openstack.org/infra/manual/developers.html#development-workflow + +Pull requests submitted through GitHub will be ignored. + +Bugs should be filed on Launchpad, not GitHub: + + https://bugs.launchpad.net/masakari diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..ddb2c34 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,33 @@ +.. masakari-specs documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +masakari-specs Design Specifications +================================================== + +Here you can find the specs, and spec template, for each release: + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/ocata/index + + +masakari-specs Repository Information +=================================================== + +.. toctree:: + :maxdepth: 2 + + README + contributing + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/specs/ocata/approved b/doc/source/specs/ocata/approved new file mode 120000 index 0000000..bb75fed --- /dev/null +++ b/doc/source/specs/ocata/approved @@ -0,0 +1 @@ +../../../../specs/ocata/approved/ \ No newline at end of file diff --git a/doc/source/specs/ocata/implemented b/doc/source/specs/ocata/implemented new file mode 120000 index 0000000..32079bf --- /dev/null +++ b/doc/source/specs/ocata/implemented @@ -0,0 +1 @@ +../../../../specs/ocata/implemented/ \ No newline at end of file diff --git a/doc/source/specs/ocata/index.rst b/doc/source/specs/ocata/index.rst new file mode 100644 index 0000000..3157d6c --- /dev/null +++ b/doc/source/specs/ocata/index.rst @@ -0,0 +1,26 @@ +========================= +Masakari Ocata Specifications +========================= + +Template: + +.. toctree:: + :maxdepth: 1 + + Specification Template (Ocata release)