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

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 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.
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: