Browse Source

Add instructions for how to use the specs project

Introduces guidelines for naming, movement, and indexing of specs
documents

Change-Id: I759ab242937f6816424770871dbf795d8aee06bd
Bryan Strassner 9 months ago
parent
commit
6104cac943

+ 18
- 0
README.rst View File

@@ -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
+====================================
10
+Building Airship Specs Documentation
11
+====================================
12
+
13
+Using the equivalent of `pip install sphinx`, install the sphinx-build command
14
+if it is not already installed.
15
+
16
+From the root of this project, issue the command `make html`.
17
+Sphinx will render the output into doc/build/html. Open
18
+doc/build/html/index.html using your browser.

+ 4
- 3
doc/source/index.rst View File

@@ -6,8 +6,10 @@
6 6
 Airship Specs Documentation
7 7
 ===========================
8 8
 
9
-Proposed Specs
10
---------------
9
+:ref:`genindex`
10
+
11
+About Specs
12
+-----------
11 13
 
12 14
 .. toctree::
13 15
    :maxdepth: 1
@@ -32,4 +34,3 @@ Implemented Specs
32 34
    :glob:
33 35
 
34 36
    specs/implemented/*
35
-

+ 8
- 0
specs/approved/_placeholder.rst View File

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

+ 8
- 0
specs/implemented/_placeholder.rst View File

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

+ 96
- 0
specs/instructions.rst View File

@@ -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
+============
14
+Instructions
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
+
26
+Indexing and Categorization
27
+---------------------------
28
+
29
+Use of the `index`_ directive in reStructuredText for each document provides
30
+the ability to generate indexes to more easily find items later. Authors are
31
+encouraged to use index entries for their documents to help with discovery.
32
+
33
+Naming
34
+------
35
+
36
+Document naming standards help readers find specs. For the Airship repository,
37
+the following document naming is recommended. The categories listed here are
38
+likely incomplete, and may need expansion to cover new cases. It is preferrable
39
+to deviate (and hopefully amend the list) than force document names into
40
+nonsense categories. Prefer using categories that have previously been used or
41
+that are listed here over new categories, but don't force the category into
42
+something that doesn't make sense.
43
+
44
+Document names should follow a pattern as follows::
45
+
46
+  [category]_title.rst
47
+
48
+Use the following guidelines to determine the category to use for a document:
49
+
50
+1) For new functionality and features, the best choice for a category is to
51
+   match a functional duty of Airship.
52
+
53
+site-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
+
58
+genesis
59
+  Used for the steps related to preparation and deployment of the genesis node
60
+  of an Airship deployment.
61
+
62
+baremetal
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
+
68
+k8s
69
+  For functionality that is about interfacing with Kubernetes directly, other
70
+  than the initial setup that is done during genesis.
71
+
72
+software
73
+  Functionality that is related to the deployment or redeployment of workload
74
+  onto the Kubernetes cluster.
75
+
76
+workflow
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
+
82
+administration
83
+  Security, logging, auditing, monitoring, and those things related to site
84
+  administrative functions of the Airship platform.
85
+
86
+2) 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
+
91
+3) 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

+ 10
- 0
specs/template.rst View File

@@ -4,10 +4,20 @@
4 4
 
5 5
   http://creativecommons.org/licenses/by/3.0/legalcode
6 6
 
7
+.. index::
8
+   single: template
9
+   single: creating specs
10
+
7 11
 .. note::
8 12
 
9 13
   Blueprints are written using ReSTructured text.
10 14
 
15
+Add index directives to help others find your spec. E.g.::
16
+
17
+  .. index::
18
+     single: template
19
+     single: creating specs
20
+
11 21
 =====================================
12 22
 Template: The title of your blueprint
13 23
 =====================================

Loading…
Cancel
Save