starlingx
/
specs
Code Issues Proposed changes
specs/specs/instructions.rst

2.5 KiB
Raw Blame History

single: instructions single: getting started

Submit a Spec

Instructions

  • Use STX_Example_Spec.rst under the approved subfolder of the applicable release 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 for the applicable release, where they will undergo review and approval in Gerrit.
  • Specs that have finished implementation should be moved to the implemented subfolder for the applicable release.

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 StarlingX 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]_[storyboard#]_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 StarlingX.
  2. For specs that are not feature focused, the component of the system may be the best choice for a category, e.g. sysinv, armada etc... When there are multiple components involved, or the concern is cross cutting, use of starlingx is an acceptable category.
  3. If the spec is related to the ecosystem StarlingX is maintained within, an appropriate category would be related to the aspect it is impacting, e.g.: git, docker, zuul, etc...