Add instructions for how to use the specs project

Introduces guidelines for naming, movement, and indexing of specs

Change-Id: I759ab242937f6816424770871dbf795d8aee06bd
Bryan Strassner 5 years ago
parent 43b300cdc5
commit 6104cac943

@ -0,0 +1,18 @@
This work is licensed under a Creative Commons Attribution 3.0 Unported
.. airship-specs-readme:
Building Airship Specs Documentation
Using the equivalent of `pip install sphinx`, install the sphinx-build command
if it is not already installed.
From the root of this project, issue the command `make html`.
Sphinx will render the output into doc/build/html. Open
doc/build/html/index.html using your browser.

@ -6,8 +6,10 @@
Airship Specs Documentation
Proposed Specs
About Specs
.. toctree::
:maxdepth: 1
@ -32,4 +34,3 @@ Implemented Specs

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

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

@ -0,0 +1,96 @@
This work is licensed under a Creative Commons Attribution 3.0 Unported
.. index::
single: instructions
single: getting started
.. _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.
Document naming standards help readers find specs. For the Airship 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::
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 Airship.
Parts of the platform that support the definition of a site, including
management of the yaml definitions, document authoring and translation, and
the collation of source documents.
Used for the steps related to preparation and deployment of the genesis node
of an Airship deployment.
Those changes to Airflow that provide for the lifecycle of bare metal
components of the system - provisioning, maintenance, and teardown. This
includes booting, hardware and network configuration, operating system, and
other host-level management
For functionality that is about interfacing with Kubernetes directly, other
than the initial setup that is done during genesis.
Functionality that is related to the deployment or redeployment of workload
onto the Kubernetes cluster.
Changes to existing workflows to provide new functionality and creation of
new workflows that span multiple other areas (e.g. baremetal, k8s, software),
or those changes that are new arrangements of existing functionality in one
or more of those other areas.
Security, logging, auditing, monitoring, and those things related to site
administrative functions of the Airship platform.
2) For specs that are not feature focused, the component of the system may
be the best choice for a category, e.g. ``shipyard``, ``armada`` etc...
When there are multiple components involved, or the concern is cross
cutting, use of ``airship`` is an acceptable category.
3) If the spec is related to the ecosystem Airship is maintained within, an
appropriate category would be related to the aspect it is impacting, e.g.:
``git``, ``docker``, ``zuul``, etc...
.. _index:
.. _Gerrit:

@ -4,10 +4,20 @@
.. index::
single: template
single: creating specs
.. note::
Blueprints 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 blueprint