summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBryan Strassner <bryan.strassner@gmail.com>2018-07-26 16:06:17 -0500
committerBryan Strassner <bryan.strassner@gmail.com>2018-07-27 11:39:32 -0500
commit6104cac943bff489702f5e05b44914cc4141d503 (patch)
tree6c713fb7d3a5986a46f90914752a433310437b86
parent43b300cdc5c007e11221009990a13696cf76d4fc (diff)
Add instructions for how to use the specs project
Introduces guidelines for naming, movement, and indexing of specs documents Change-Id: I759ab242937f6816424770871dbf795d8aee06bd
Notes
Notes (review): Code-Review+2: Felipe Monteiro <felipe.monteiro@att.com> Code-Review+2: Marshall Margenau <mmargenau@gmail.com> Workflow+1: Marshall Margenau <mmargenau@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Fri, 27 Jul 2018 19:01:32 +0000 Reviewed-on: https://review.openstack.org/586352 Project: openstack/airship-specs Branch: refs/heads/master
-rw-r--r--README.rst18
-rw-r--r--doc/source/index.rst7
-rw-r--r--specs/approved/_placeholder.rst8
-rw-r--r--specs/implemented/_placeholder.rst8
-rw-r--r--specs/instructions.rst96
-rw-r--r--specs/template.rst10
6 files changed, 144 insertions, 3 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..d3132a5
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,18 @@
1..
2 This work is licensed under a Creative Commons Attribution 3.0 Unported
3 License.
4
5 http://creativecommons.org/licenses/by/3.0/legalcode
6
7.. airship-specs-readme:
8
9====================================
10Building Airship Specs Documentation
11====================================
12
13Using the equivalent of `pip install sphinx`, install the sphinx-build command
14if it is not already installed.
15
16From the root of this project, issue the command `make html`.
17Sphinx will render the output into doc/build/html. Open
18doc/build/html/index.html using your browser.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 213ab7c..618f93f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,8 +6,10 @@
6Airship Specs Documentation 6Airship Specs Documentation
7=========================== 7===========================
8 8
9Proposed Specs 9:ref:`genindex`
10-------------- 10
11About Specs
12-----------
11 13
12.. toctree:: 14.. toctree::
13 :maxdepth: 1 15 :maxdepth: 1
@@ -32,4 +34,3 @@ Implemented Specs
32 :glob: 34 :glob:
33 35
34 specs/implemented/* 36 specs/implemented/*
35
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 @@
1.. placeholder:
2
3===========
4Placeholder
5===========
6
7This file is a placeholder and should be deleted when the first spec is moved
8to 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 @@
1.. placeholder:
2
3===========
4Placeholder
5===========
6
7This file is a placeholder and should be deleted when the first spec is moved
8to this directory.
diff --git a/specs/instructions.rst b/specs/instructions.rst
new file mode 100644
index 0000000..d86e9ef
--- /dev/null
+++ b/specs/instructions.rst
@@ -0,0 +1,96 @@
1..
2 This work is licensed under a Creative Commons Attribution 3.0 Unported
3 License.
4
5 http://creativecommons.org/licenses/by/3.0/legalcode
6
7.. index::
8 single: instructions
9 single: getting started
10
11.. _instructions:
12
13============
14Instructions
15============
16
17- Use the template.rst as the basis of your specification.
18- Attempt to detail each applicable section.
19- If a section does not apply, use N/A, and optionally provide
20 a short explanation.
21- New specs for review should be placed in the ``approved`` subfolder, where
22 they will undergo review and approval in Gerrit_.
23- Specs that have finished implementation should be moved to the
24 ``implemented`` subfolder
25
26Indexing and Categorization
27---------------------------
28
29Use of the `index`_ directive in reStructuredText for each document provides
30the ability to generate indexes to more easily find items later. Authors are
31encouraged to use index entries for their documents to help with discovery.
32
33Naming
34------
35
36Document naming standards help readers find specs. For the Airship repository,
37the following document naming is recommended. The categories listed here are
38likely incomplete, and may need expansion to cover new cases. It is preferrable
39to deviate (and hopefully amend the list) than force document names into
40nonsense categories. Prefer using categories that have previously been used or
41that are listed here over new categories, but don't force the category into
42something that doesn't make sense.
43
44Document names should follow a pattern as follows::
45
46 [category]_title.rst
47
48Use the following guidelines to determine the category to use for a document:
49
501) For new functionality and features, the best choice for a category is to
51 match a functional duty of Airship.
52
53site-definition
54 Parts of the platform that support the definition of a site, including
55 management of the yaml definitions, document authoring and translation, and
56 the collation of source documents.
57
58genesis
59 Used for the steps related to preparation and deployment of the genesis node
60 of an Airship deployment.
61
62baremetal
63 Those changes to Airflow that provide for the lifecycle of bare metal
64 components of the system - provisioning, maintenance, and teardown. This
65 includes booting, hardware and network configuration, operating system, and
66 other host-level management
67
68k8s
69 For functionality that is about interfacing with Kubernetes directly, other
70 than the initial setup that is done during genesis.
71
72software
73 Functionality that is related to the deployment or redeployment of workload
74 onto the Kubernetes cluster.
75
76workflow
77 Changes to existing workflows to provide new functionality and creation of
78 new workflows that span multiple other areas (e.g. baremetal, k8s, software),
79 or those changes that are new arrangements of existing functionality in one
80 or more of those other areas.
81
82administration
83 Security, logging, auditing, monitoring, and those things related to site
84 administrative functions of the Airship platform.
85
862) For specs that are not feature focused, the component of the system may
87 be the best choice for a category, e.g. ``shipyard``, ``armada`` etc...
88 When there are multiple components involved, or the concern is cross
89 cutting, use of ``airship`` is an acceptable category.
90
913) If the spec is related to the ecosystem Airship is maintained within, an
92 appropriate category would be related to the aspect it is impacting, e.g.:
93 ``git``, ``docker``, ``zuul``, etc...
94
95.. _index: http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index
96.. _Gerrit: https://review.openstack.org/#/q/project:openstack/airship-specs
diff --git a/specs/template.rst b/specs/template.rst
index 8b753f0..01577ee 100644
--- a/specs/template.rst
+++ b/specs/template.rst
@@ -4,10 +4,20 @@
4 4
5 http://creativecommons.org/licenses/by/3.0/legalcode 5 http://creativecommons.org/licenses/by/3.0/legalcode
6 6
7.. index::
8 single: template
9 single: creating specs
10
7.. note:: 11.. note::
8 12
9 Blueprints are written using ReSTructured text. 13 Blueprints are written using ReSTructured text.
10 14
15Add index directives to help others find your spec. E.g.::
16
17 .. index::
18 single: template
19 single: creating specs
20
11===================================== 21=====================================
12Template: The title of your blueprint 22Template: The title of your blueprint
13===================================== 23=====================================