airship
/
specs
Code Issues Proposed changes
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd973ea29e6'
${ noResults }
specs/specs/instructions.rst

4.0 KiB
Raw Blame History

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.

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