You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
104 lines
4.0 KiB
ReStructuredText
104 lines
4.0 KiB
ReStructuredText
..
|
|
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 of
|
|
``1.x`` or ``2.x`` directories (depending on Airship version they primarily
|
|
belong to), where they will undergo review and approval in Gerrit_.
|
|
- Test if the spec file renders correctly in a web-browser by running
|
|
``make docs`` command and opening ``doc/build/html/index.html`` in a
|
|
web-browser. Ubuntu needs the following packages to be installed::
|
|
|
|
apt-get install -y make tox gcc python3-dev
|
|
|
|
- Specs that have finished implementation should be moved to the
|
|
``implemented`` subfolder of respective ``1.x`` or ``2.x`` directories.
|
|
|
|
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 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::
|
|
|
|
[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 Airship.
|
|
|
|
site-definition
|
|
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.
|
|
|
|
genesis
|
|
Used for the steps related to preparation and deployment of the genesis node
|
|
of an Airship deployment.
|
|
|
|
baremetal
|
|
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
|
|
|
|
k8s
|
|
For functionality that is about interfacing with Kubernetes directly, other
|
|
than the initial setup that is done during genesis.
|
|
|
|
software
|
|
Functionality that is related to the deployment or redeployment of workload
|
|
onto the Kubernetes cluster.
|
|
|
|
workflow
|
|
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.
|
|
|
|
administration
|
|
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: http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index
|
|
.. _Gerrit: https://review.openstack.org/#/q/project:openstack/airship-specs
|