Create initial template for specifications

Change-Id: I16a0fd0ff814ba38d442be218cc8daa77f8f1394
Signed-off-by: Saul Wold <sgw@linux.intel.com>
This commit is contained in:
Saul Wold 2018-08-24 14:06:02 -07:00
parent 83d8e4413d
commit 8f0d710960
10 changed files with 343 additions and 0 deletions

104
.gitignore vendored Normal file
View File

@ -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/

8
.zuul.yaml Normal file
View File

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

5
README.rst Normal file
View File

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

View File

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

View File

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

View File

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

63
specs/instructions.rst Normal file
View File

@ -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

105
specs/template.rst Normal file
View File

@ -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)

2
test-requirements.txt Normal file
View File

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

32
tox.ini Normal file
View File

@ -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}