Create initial template for specifications

Change-Id: I16a0fd0ff814ba38d442be218cc8daa77f8f1394
Signed-off-by: Saul Wold <sgw@linux.intel.com>

.gitignore

@@ -0,0 +1,104 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/

.zuul.yaml

@@ -0,0 +1,8 @@
+---
+- project:
+    check:
+      jobs:
+        - openstack-tox-linters
+    gate:
+      jobs:
+        - openstack-tox-linters

README.rst

@@ -0,0 +1,5 @@
+========================
+StarlingX specifications
+========================
+
+This repository contains specifications for the StarlingX project.

doc/source/_placeholder.rst

@@ -0,0 +1,8 @@
+.. placeholder:
+
+===========
+Placeholder
+===========
+
+This file is a placeholder and should be deleted when the first spec is moved
+to this directory.

specs/approved/_placeholder.rst

@@ -0,0 +1,8 @@
+.. placeholder:
+
+===========
+Placeholder
+===========
+
+This file is a placeholder and should be deleted when the first spec is moved
+to this directory.

specs/implemented/_placeholder.rst

@@ -0,0 +1,8 @@
+.. placeholder:
+
+===========
+Placeholder
+===========
+
+This file is a placeholder and should be deleted when the first spec is moved
+to this directory.

specs/instructions.rst

@@ -0,0 +1,63 @@
+..
+  This work is licensed under a Creative Commons Attribution 3.0 Unported
+  License.
+
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+.. index::
+   single: instructions
+   single: getting started
+
+.. _instructions:
+
+============
+Instructions
+============
+
+- Use the template.rst as the basis of your specification.
+- Attempt to detail each applicable section.
+- If a section does not apply, use N/A, and optionally provide
+  a short explanation.
+- New specs for review should be placed in the ``approved`` subfolder, where
+  they will undergo review and approval in Gerrit_.
+- Specs that have finished implementation should be moved to the
+  ``implemented`` subfolder.
+
+Indexing and Categorization
+---------------------------
+
+Use of the `index`_ directive in reStructuredText for each document provides
+the ability to generate indexes to more easily find items later. Authors are
+encouraged to use index entries for their documents to help with discovery.
+
+Naming
+------
+
+Document naming standards help readers find specs. For the StarlingX repository,
+the following document naming is recommended. The categories listed here are
+likely incomplete, and may need expansion to cover new cases. It is preferrable
+to deviate (and hopefully amend the list) than force document names into
+nonsense categories. Prefer using categories that have previously been used or
+that are listed here over new categories, but don't force the category into
+something that doesn't make sense.
+
+Document names should follow a pattern as follows::
+
+  [category]_title.rst
+
+Use the following guidelines to determine the category to use for a document:
+
+1) For new functionality and features, the best choice for a category is to
+   match a functional duty of StarlingX.
+
+2) For specs that are not feature focused, the component of the system may
+   be the best choice for a category, e.g. ``sysinv``, ``armada`` etc...
+   When there are multiple components involved, or the concern is cross
+   cutting, use of ``starlingx`` is an acceptable category.
+
+3) If the spec is related to the ecosystem StarlingX is maintained within, an
+   appropriate category would be related to the aspect it is impacting, e.g.:
+   ``git``, ``docker``, ``zuul``, etc...
+
+.. _index: http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index
+.. _Gerrit: https://review.openstack.org/#/q/project:openstack/stx-specs

specs/template.rst

@@ -0,0 +1,105 @@
+..
+  This work is licensed under a Creative Commons Attribution 3.0 Unported
+  License.
+
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+.. index::
+   single: template
+   single: creating specs
+
+.. note::
+
+  Specifications are written using ReSTructured text.
+
+Add index directives to help others find your spec. E.g.::
+
+  .. index::
+     single: template
+     single: creating specs
+
+=========================================
+Template: The title of your specification
+=========================================
+
+Introduction paragraph -- What is this specification about?
+
+Links
+=====
+
+Include pertinent links to where the work is being tracked (e.g. Storyboard),
+as well as any other foundational information that may lend clarity to this
+specification
+
+Problem description
+===================
+
+A detailed description of the problem being addressed or solved
+
+Impacted components
+===================
+
+List the StarlingX components that are impacted
+
+Proposed change
+===============
+
+Provide a detailed description of the change being proposed. Include how the
+problem will be addressed or solved.
+
+If this is an incremental part of a larger solution or effort, provide the
+specific scope of this specification, and how it fits into the overarching
+solution.
+
+Details of changes to specific StarlingX components should be specified in this
+section, as well as interaction between those components.
+
+Special attention should be given to interfaces between components. New
+interfaces shuld attempt to follow established patterns within StarlingX, or
+should be evaluated for suitability as new precedent.
+
+If this specification changes testing needs or approaches, that information
+should be disclosed here, and should be regarded as part of the deliverable
+related to this design.
+
+If this specification introduces new functionality that requires new kinds of
+documentation, or a change to the documentation processes, that information
+should be included in this section.
+
+Security impact
+---------------
+
+Details of any security-related concerns that this proposed change introduces
+or addresses.
+
+Performance impact
+------------------
+
+Analysis of performance changes that are introduced or addressed with this
+proposed design.
+
+Alternatives
+------------
+
+If other approaches were considered, include a summary of those here, and a
+short discussion of why the proposed approach is preferred.
+
+Implementation
+==============
+
+If known, include any information detailing assigned individuals, proposed
+milestones, intermediate deliverable products, and work items.
+
+If there are Assignee(s) or Work Items, use a sub-heading for that
+information.
+
+Dependencies
+============
+
+If there are any dependencies on other work, specification, or other things that
+impact the ability to deliver this solution, include that information here.
+
+References
+==========
+
+Any external references (other than the direct links above)

test-requirements.txt

@@ -0,0 +1,2 @@
+PyYAML>=3.1.0
+yamllint>=0.5.2

tox.ini

@@ -0,0 +1,32 @@
+[tox]
+envlist = linters
+minversion = 2.3
+skipsdist = True
+
+[testenv]
+basepython = python3
+install_command = pip install -U {opts} {packages}
+setenv = VIRTUAL_ENV={envdir}
+         OS_STDOUT_CAPTURE=1
+         OS_STDERR_CAPTURE=1
+         OS_TEST_TIMEOUT=60
+deps = -r{toxinidir}/test-requirements.txt
+
+[testenv:docs]
+basepython = python3
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/doc/requirements.txt
+commands =
+  sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
+
+[testenv:linters]
+whitelist_externals = bash
+commands =
+  bash -c "find {toxinidir}                   \
+            \( -name .tox -prune \)           \
+            -o -type f -name '*.yaml'         \
+            -print0 | xargs -0 yamllint"
+
+[testenv:venv]
+commands = {posargs}