From 8f0d710960d2900fbf4e46f59713c80d7bb202a7 Mon Sep 17 00:00:00 2001 From: Saul Wold Date: Fri, 24 Aug 2018 14:06:02 -0700 Subject: [PATCH] Create initial template for specifications Change-Id: I16a0fd0ff814ba38d442be218cc8daa77f8f1394 Signed-off-by: Saul Wold --- .gitignore | 104 ++++++++++++++++++++++++++++ .zuul.yaml | 8 +++ README.rst | 5 ++ doc/source/_placeholder.rst | 8 +++ specs/approved/_placeholder.rst | 8 +++ specs/implemented/_placeholder.rst | 8 +++ specs/instructions.rst | 63 +++++++++++++++++ specs/template.rst | 105 +++++++++++++++++++++++++++++ test-requirements.txt | 2 + tox.ini | 32 +++++++++ 10 files changed, 343 insertions(+) create mode 100644 .gitignore create mode 100644 .zuul.yaml create mode 100644 README.rst create mode 100644 doc/source/_placeholder.rst create mode 100644 specs/approved/_placeholder.rst create mode 100644 specs/implemented/_placeholder.rst create mode 100644 specs/instructions.rst create mode 100644 specs/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..894a44c --- /dev/null +++ b/.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/ diff --git a/.zuul.yaml b/.zuul.yaml new file mode 100644 index 0000000..7ccbd0a --- /dev/null +++ b/.zuul.yaml @@ -0,0 +1,8 @@ +--- +- project: + check: + jobs: + - openstack-tox-linters + gate: + jobs: + - openstack-tox-linters diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..4bf352d --- /dev/null +++ b/README.rst @@ -0,0 +1,5 @@ +======================== +StarlingX specifications +======================== + +This repository contains specifications for the StarlingX project. diff --git a/doc/source/_placeholder.rst b/doc/source/_placeholder.rst new file mode 100644 index 0000000..0cd761b --- /dev/null +++ b/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. diff --git a/specs/approved/_placeholder.rst b/specs/approved/_placeholder.rst new file mode 100644 index 0000000..0cd761b --- /dev/null +++ b/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. diff --git a/specs/implemented/_placeholder.rst b/specs/implemented/_placeholder.rst new file mode 100644 index 0000000..0cd761b --- /dev/null +++ b/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. diff --git a/specs/instructions.rst b/specs/instructions.rst new file mode 100644 index 0000000..3e670c4 --- /dev/null +++ b/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 diff --git a/specs/template.rst b/specs/template.rst new file mode 100644 index 0000000..00fe3c6 --- /dev/null +++ b/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) diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..266f880 --- /dev/null +++ b/test-requirements.txt @@ -0,0 +1,2 @@ +PyYAML>=3.1.0 +yamllint>=0.5.2 diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..4a2cc00 --- /dev/null +++ b/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}