Update and simplification of contribution guides
- Simplify docs contribution guide, using refs to OpenStack docs - Minor formatting edits in other guides to make consistent - Move doc to developer resources - add link(s) to wiki from landing page Patchset 2: Added ordered and enumerated lists, wording improvements per feedback. Change-Id: I3b15a8127c0d742d726389e2b561424fca82567c Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
parent
d1c9155684
commit
20269cc03f
|
|
@ -1,47 +1,52 @@
|
|||
=====================
|
||||
API contributor guide
|
||||
=====================
|
||||
===================================
|
||||
API Documentation Contributor Guide
|
||||
===================================
|
||||
|
||||
OpenStack API working group has defined a guideline to follow for API
|
||||
documentation when a project provides a REST API service. API
|
||||
documentation information comes from RST source files stored in the
|
||||
project repository, that when built, generate HTML files.
|
||||
|
||||
For additional information about the OpenStack guideline, refer to the
|
||||
`OpenStack API documentation guide <https://docs.openstack.org/doc-contrib-guide/api-guides.html>`_.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
---------
|
||||
Locations
|
||||
---------
|
||||
|
||||
OpenStack API working group has defined a guideline to follow for API
|
||||
documentation when a project provides a REST API service. API
|
||||
documentation information comes from RST source files stored in the
|
||||
project repository, that when built, generate HTML files. More details
|
||||
about the OpenStack API documentation can be found at:
|
||||
https://docs.openstack.org/doc-contrib-guide/api-guides.html.
|
||||
StarlingX API reference documentation exists in the following projects:
|
||||
|
||||
StarlingX API Reference documentation exists in the following projects:
|
||||
* `starlingx/config`_: StarlingX System Configuration Management
|
||||
* `starlingx/docs`_: StarlingX Documentation
|
||||
|
||||
- `starlingx/config`_: StarlingX System Configuration Management
|
||||
- `starlingx/docs`_: StarlingX Documentation
|
||||
|
||||
- *stx-python-cinderclient* // only StarlingX-specific
|
||||
* *stx-python-cinderclient* // only StarlingX-specific
|
||||
extensions to Cinder API are documented here
|
||||
- *stx-nova* // only StarlingX-specific extensions to Nova
|
||||
* *stx-nova* // only StarlingX-specific extensions to Nova
|
||||
API are documented here
|
||||
- *stx-glance* // only StarlingX-specific extensions to
|
||||
* *stx-glance* // only StarlingX-specific extensions to
|
||||
Glance API are documented here
|
||||
- *stx-neutron* // only StarlingX-specific extensions to
|
||||
* *stx-neutron* // only StarlingX-specific extensions to
|
||||
Neutron API are documented here
|
||||
|
||||
- `starlingx/distcloud`_: StarlingX Distributed Cloud
|
||||
- `starlingx/fault`_: StarlingX Fault Management
|
||||
- `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service
|
||||
* `starlingx/distcloud`_: StarlingX Distributed Cloud
|
||||
* `starlingx/fault`_: StarlingX Fault Management
|
||||
* `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service
|
||||
Management
|
||||
- `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware
|
||||
* `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware
|
||||
Maintenance
|
||||
- `starlingx/nfv`_: StarlingX NFVI Orchestration
|
||||
* `starlingx/nfv`_: StarlingX NFVI Orchestration
|
||||
|
||||
--------------------
|
||||
Directory Structures
|
||||
Directory structures
|
||||
--------------------
|
||||
|
||||
The directory structure of the API Reference documentation under each
|
||||
StarlingX project repository is fixed. Here is an example showing
|
||||
`starlingx/config`_ StarlingX System Configuration Management
|
||||
The directory structure of the API reference documentation under each
|
||||
StarlingX project repository is fixed. This example shows the `starlingx/config`_
|
||||
project:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -51,36 +56,43 @@ StarlingX project repository is fixed. Here is an example showing
|
|||
├── conf.py
|
||||
└── index.rst
|
||||
|
||||
The initial modifications and additions to enable the API Documentation
|
||||
The initial modifications and additions to enable the API documentation
|
||||
service in each StarlingX project are as follows:
|
||||
|
||||
- **.gitignore** modifications to ignore the building directories and
|
||||
HTML files for the API reference
|
||||
- **.zuul.yaml** modifications to add the jobs to build and publish the
|
||||
api-ref document
|
||||
- **api-ref/source** directory creation to store your API Reference
|
||||
project directory
|
||||
- **api-ref/source/conf.py** configuration file to determine the HTML
|
||||
theme, Sphinx extensions and project information
|
||||
- **api-ref/source/index.rst** source file to create your index RST
|
||||
source file
|
||||
- **doc/requiremets.txt** modifications to add the os-api-ref Sphinx
|
||||
extension
|
||||
- **tox.ini** modifications to add the configuration to build the API
|
||||
reference locally
|
||||
``.gitignore``
|
||||
Modifications to ignore the building directories and HTML files for the API
|
||||
reference.
|
||||
|
||||
``.zuul.yaml``
|
||||
Modifications to add jobs to build and publish the ``api-ref`` document.
|
||||
|
||||
``api-ref/source``
|
||||
Directory created to store your API Reference project directory.
|
||||
|
||||
``api-ref/source/conf.py``
|
||||
Configuration file to set the HTML theme, Sphinx extensions, and project
|
||||
information.
|
||||
|
||||
``api-ref/source/index.rst``
|
||||
Source file to create your index RST source file.
|
||||
|
||||
``doc/requiremets.txt``
|
||||
Modifications to add the ``os-api-ref`` Sphinx extension.
|
||||
|
||||
``tox.ini``
|
||||
Modifications to add the configuration to build the API reference locally.
|
||||
|
||||
See `starlingx/config`_ [Doc] OpenStack API Reference Guide as an example of this
|
||||
first commit: https://review.opendev.org/#/c/603258/
|
||||
|
||||
----------------------------
|
||||
Creating the RST Source File
|
||||
----------------------------
|
||||
--------------------------
|
||||
Create the RST source file
|
||||
--------------------------
|
||||
|
||||
Once the API Documentation service has been enabled, you create the RST
|
||||
source files that document the API operations under the same API
|
||||
Reference documentation project directory. The following shows the RST
|
||||
source file for the `starlingx/config`_ StarlingX System Configuration
|
||||
Management: Configuration API v1
|
||||
Once the API documentation service has been enabled, create the RST source files
|
||||
that document the API operations under the same API reference documentation
|
||||
project directory. The following example shows the RST source file for the
|
||||
`starlingx/config`_ StarlingX System Configuration Management Configuration API v1:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -88,18 +100,14 @@ Management: Configuration API v1
|
|||
└── source
|
||||
└── api-ref-sysinv-v1-config.rst
|
||||
|
||||
-----------------------
|
||||
Creating the Index File
|
||||
-----------------------
|
||||
---------------------
|
||||
Create the index file
|
||||
---------------------
|
||||
|
||||
After providing the RST source file as shown in the previous example,
|
||||
you add the **index.rst** file. This file provides captioning, a brief
|
||||
description of the document, and the table-of-contents structure with
|
||||
depth restrictions. The **index.rst** file resides in the same folder as
|
||||
the RST source file.
|
||||
|
||||
Here is an example using the `starlingx/config`_ StarlingX System
|
||||
Configuration Management: Configuration API v1:
|
||||
After providing the RST source file as shown in the previous example, add the
|
||||
``index.rst`` file. This file provides captioning, a brief description of the
|
||||
document, and the Table-of-Contents structure with depth restrictions. The
|
||||
``index.rst`` file is located in the same folder as the RST source file:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -108,8 +116,8 @@ Configuration Management: Configuration API v1:
|
|||
|___api-ref-sysinv-v1-config.rst
|
||||
|___index.rst
|
||||
|
||||
The syntax of the **index.rst** file is fixed. Following shows the
|
||||
**index.rst** file used in the `starlingx/config`_:
|
||||
The syntax of the ``index.rst`` file is fixed. The following example shows the
|
||||
``index.rst`` file used in the `starlingx/config`_:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -124,26 +132,30 @@ The syntax of the **index.rst** file is fixed. Following shows the
|
|||
api-ref-sys-v1-config
|
||||
|
||||
|
||||
Following are explanations for each of the four areas of the
|
||||
**index.rst** file:
|
||||
The ``index.rst`` file contains:
|
||||
|
||||
- **Reference title:** Literal title that is used in the rendered
|
||||
document. In this case it is "stx-config API Reference".
|
||||
- **Reference summary:** Literal summary of the rendered document. In
|
||||
this case it is "StarlingX System Configuration Management".
|
||||
- **Table-of-Contents tree structure and depth parameters:** The
|
||||
directive to create a TOC and to limit the depth of topics to "2".
|
||||
- **RST source file root name:** The source file to use as content. In
|
||||
this case, the file reference is "api-ref-sys-v1-config". This
|
||||
references the **api-ref-sys-v1-config.rst** file in the same folder
|
||||
as the **index.rst** file.
|
||||
``Reference title``
|
||||
Literal title that is used in the rendered document. In this case it is
|
||||
"stx-config API Reference".
|
||||
|
||||
``Reference summary``
|
||||
Literal summary of the rendered document. In this case it is
|
||||
"StarlingX System Configuration Management".
|
||||
|
||||
``Table-of-Contents tree structure and depth parameters``
|
||||
The directive to create a TOC and to limit the depth of topics to "2".
|
||||
|
||||
``RST source file root name``
|
||||
The source file to use as content. In this case, the file reference is
|
||||
`api-ref-sys-v1-config`. This references the ``api-ref-sys-v1-config.rst``
|
||||
file in the same folder as the ``index.rst`` file.
|
||||
|
||||
------------------
|
||||
REST METHOD Syntax
|
||||
REST method syntax
|
||||
------------------
|
||||
|
||||
Following is the syntax for each REST METHOD in the RST source file
|
||||
(e.g. **api-ref-sys-v1-config.rst**).
|
||||
This section describes the syntax for each REST method in the RST source file
|
||||
(for example ``api-ref-sys-v1-config.rst``).
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -225,18 +237,16 @@ Following is the syntax for each REST METHOD in the RST source file
|
|||
]
|
||||
}
|
||||
|
||||
|
||||
|
||||
------------------------------------
|
||||
Building the Reference Documentation
|
||||
------------------------------------
|
||||
---------------------------------
|
||||
Build the reference documentation
|
||||
---------------------------------
|
||||
|
||||
To build the API reference documentation locally in HTML format, use the
|
||||
following command:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ tox -e api-ref
|
||||
tox -e api-ref
|
||||
|
||||
The resulting directories and HTML files looks like:
|
||||
|
||||
|
|
@ -253,86 +263,12 @@ The resulting directories and HTML files looks like:
|
|||
...
|
||||
└── _static
|
||||
|
||||
-----------------------------------------
|
||||
View the rendered reference documentation
|
||||
-----------------------------------------
|
||||
|
||||
--------------------------
|
||||
Closing Out a Bug or Story
|
||||
--------------------------
|
||||
|
||||
If you are modifying a document as a result of a defect or
|
||||
feature that is associated with a StoryBoard Story or Launchpad
|
||||
Bug, you must take steps to link your submission (Gerrit Review)
|
||||
to the story or bug.
|
||||
|
||||
To link a story, add the following lines in your
|
||||
commit message.
|
||||
Be sure to use the actual story ID and task ID:
|
||||
|
||||
* Story: $story_id
|
||||
* Task: $task_id
|
||||
|
||||
Following is an example that links a Gerrit Review with Story
|
||||
2003375 and Task 2444:
|
||||
|
||||
::
|
||||
|
||||
Change the tox.ini directory regarding tox.ini dependencies
|
||||
|
||||
Story: 2003375
|
||||
Task: 24444
|
||||
|
||||
**NOTE:** You must provide a blank line before the lines
|
||||
used to identify the story and the task.
|
||||
If you do not provide this line, your submission will not
|
||||
link to the Storyboard's story.
|
||||
|
||||
To link a bug, add the approprite lines in your commit message.
|
||||
Be sure to provide the actual bug numbers:
|
||||
|
||||
* Closes-Bug: $bug_id
|
||||
* Partial-Bug: $bug_id
|
||||
* Related-Bug: $bug_id
|
||||
|
||||
If your fix requires multiple commits, use "Partial-Bug"
|
||||
for all the commits except the final one.
|
||||
For the final commit, use "Closes-Bug".
|
||||
|
||||
Following is an example commit message that closes out bug
|
||||
1804024:
|
||||
|
||||
::
|
||||
|
||||
AIO Hardware Requirements: Updated AIO HW requirements.
|
||||
|
||||
Added Small HW form factor information simplex/duplex
|
||||
AIO hardware requirements.
|
||||
|
||||
Closes-Bug: #1804024
|
||||
|
||||
When you associate a story or bug with a Gerrit review, Gerrit
|
||||
automatically updates the status of the story or bug once the
|
||||
commit is merged.
|
||||
Again, be sure to provide a blank line just before the line
|
||||
identifying the bug.
|
||||
|
||||
You can find more information on the StarlingX code submission
|
||||
guidelines on the
|
||||
`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
|
||||
|
||||
To see the list of defects against StarlingX, see the
|
||||
`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
|
||||
|
||||
--------------------------------------------
|
||||
Viewing the Rendered Reference Documentation
|
||||
--------------------------------------------
|
||||
|
||||
To view the rendered HTML API Reference document in a browser, open up
|
||||
the **index.html** file.
|
||||
|
||||
**NOTE:** The PDF build uses a different tox environment and is
|
||||
currently not supported for StarlingX.
|
||||
|
||||
|
||||
|
||||
To view the rendered HTML API reference document in a browser, open up
|
||||
the ``index.html`` file.
|
||||
|
||||
.. _starlingx/config: https://opendev.org/starlingx/config
|
||||
.. _starlingx/docs: https://opendev.org/starlingx/docs
|
||||
|
|
|
|||
|
|
@ -2,9 +2,11 @@
|
|||
StarlingX Development Process
|
||||
=============================
|
||||
|
||||
This section describes the StarlingX development process.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
:depth: 1
|
||||
|
||||
------------
|
||||
Introduction
|
||||
|
|
|
|||
|
|
@ -1,288 +1,433 @@
|
|||
===============================
|
||||
Documentation contributor guide
|
||||
Documentation Contributor Guide
|
||||
===============================
|
||||
|
||||
This guide provides information that allows you to contribute to the
|
||||
`StarlingX documentation <https://docs.starlingx.io/>`_.
|
||||
This section describes the guidelines for contributing to the StarlingX
|
||||
documentation.
|
||||
|
||||
Information common to OpenStack workflow, writing styles, and conventions
|
||||
is not included in this guide. Instead refer to the
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
------------------
|
||||
General guidelines
|
||||
------------------
|
||||
|
||||
The StarlingX documentation uses reStructuredText (RST) markup syntax with
|
||||
Sphinx extensions. Most writing and markup conventions are based on the
|
||||
`OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
|
||||
|
||||
---------
|
||||
Locations
|
||||
---------
|
||||
When writing documentation, follow the StarlingX documentation guidelines:
|
||||
|
||||
StarlingX documentation consists of several types of manuals and is found
|
||||
in the `starlingx/docs`_ and `starlingx/specs`_ repositories.
|
||||
* `Writing style`_
|
||||
* `RST conventions`_
|
||||
|
||||
You can clone these repositories by:
|
||||
Verify that your changes render properly by `building the documentation locally <https://docs.openstack.org/doc-contrib-guide/docs-builds.html>`_.
|
||||
|
||||
******************
|
||||
Contribute content
|
||||
******************
|
||||
|
||||
If you are looking for work to complete, review these reports:
|
||||
|
||||
* Refer to the `StarlingX documentation StoryBoard <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that need content. Many topics have stub pages in the documentation with a link to the associated story.
|
||||
|
||||
* Find open `documentation bugs on Launchpad <https://bugs.launchpad.net/starlingx/+bugs?field.tag=stx.docs>`_.
|
||||
|
||||
|
||||
When creating a Gerrit review, link the associated story, task, or bug in the
|
||||
comment, according to `Starlingx Code Submission Guidelines <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
|
||||
|
||||
For example, link a story and task in a comment:
|
||||
|
||||
::
|
||||
|
||||
$ git clone https://opendev.org/starlingx/docs.git
|
||||
$ git clone https://opendev.org/starlingx/specs.git
|
||||
Brief description of change.
|
||||
|
||||
These projects contain hierarchy that organizes the documentation by topic:
|
||||
Detailed description of change.
|
||||
|
||||
Installation Guide
|
||||
Describes how to install StarlingX onto Bare Metal or into a virtual
|
||||
environment.
|
||||
Story: $story_id
|
||||
Task: $task_id
|
||||
|
||||
Developer Guide
|
||||
Describes how to build a StarlingX ISO image from the "master" branch.
|
||||
Or, to link to the bug that the review fixes:
|
||||
|
||||
Project Specifications
|
||||
Describes specifications, specification templates, and processes for
|
||||
submitting a specification.
|
||||
::
|
||||
|
||||
REST API Reference
|
||||
Describes StarlingX APIs.
|
||||
Brief description of bug fix.
|
||||
|
||||
Release Notes
|
||||
Provides release-specific information.
|
||||
Detailed description of bug fix.
|
||||
|
||||
Contribute
|
||||
Provides guides on how to contribute to StarlingX API documentation,
|
||||
release notes, and general documentation.
|
||||
Closes-Bug: $bug_id
|
||||
|
||||
--------------------
|
||||
Directory Structures
|
||||
--------------------
|
||||
-----------------
|
||||
Docs organization
|
||||
-----------------
|
||||
|
||||
Directory structures vary depending on the type of documentation involved.
|
||||
Think of the structure as one or more RST files per book.
|
||||
Documentation for StarlingX is organized into the following sections:
|
||||
|
||||
* A simple book consists of a single **index.rst** file.
|
||||
* A more complicated book could consist of an **index.rst** file as the book's
|
||||
landing page and a set of additional RST files for major sections of the book.
|
||||
:doc:`/introduction/index`
|
||||
Overview of the StarlingX project.
|
||||
|
||||
The structure for the API Reference documentation deserves some extra explanation.
|
||||
Most RST files for the API Reference content reside in top-level
|
||||
StarlingX repositories, for example `starlingx/metal`_ or `starlingx/config`_.
|
||||
However, four API Reference RST files reside in `starlingx/docs`_,
|
||||
in **/api-ref/source**:
|
||||
:doc:`/deploy_install_guides/index`
|
||||
Release-specific installation and deployment guides.
|
||||
|
||||
* "Block Storage"
|
||||
* "Compute"
|
||||
* "Image"
|
||||
* "Network".
|
||||
:doc:`/configuration/index`
|
||||
Configuration references for post-installation StarlingX system configuration.
|
||||
|
||||
While there is a **/api-ref/source/index.rst** file along
|
||||
side these other four RST files, it exists only because the Sphinx process
|
||||
needs that index file to build out the final web documentation tree.
|
||||
The actual landing page (content) for the API Reference documents
|
||||
is in the **/doc/source/api-ref/index.rst** file.
|
||||
:doc:`/operations/index`
|
||||
System administration and maintenance guides.
|
||||
|
||||
In the `starlingx/specs`_ project, the **/doc/source/index.rst**
|
||||
file is the main landing page for the StarlingX specifications page
|
||||
(<https://docs.starlingx.io/specs/index.html>`_).
|
||||
:doc:`/api-ref/index`
|
||||
REST API references for the StarlingX project. For additional information about
|
||||
where REST API documentation is located, see `API documentation`_.
|
||||
|
||||
The **/specs/2019.03** area contains the RST files for approved and
|
||||
:doc:`/cli_ref/index`
|
||||
Reference for the StarlingX project command line interface (CLI).
|
||||
|
||||
:doc:`/developer_resources/index`
|
||||
Resources for developers using or building StarlingX.
|
||||
|
||||
:doc:`/releasenotes/index`
|
||||
Release notes for all StarlingX releases.
|
||||
|
||||
:doc:`/contributor/index`
|
||||
Overview and guidelines for contributing to StarlingX documentation.
|
||||
|
||||
*****************
|
||||
API documentation
|
||||
*****************
|
||||
|
||||
The structure and location of the REST API documentation deserves extra explanation.
|
||||
|
||||
Most REST API content is generated from the StarlingX project associated with the
|
||||
API. For example, the documentation for the StarlingX metal REST API is
|
||||
generated from the `metal repository <https://opendev.org/starlingx/metal>`_.
|
||||
|
||||
API references for StarlingX extensions are part of the docs repository, located
|
||||
in the ``api-ref`` project:
|
||||
|
||||
* StarlingX extensions to the OpenStack Block Storage API
|
||||
* StarlingX extensions to the OpenStack Compute API
|
||||
* StarlingX extensions to the OpenStack Image API
|
||||
* StarlingX extensions to the OpenStack Networking API
|
||||
|
||||
The ``api-ref`` project also contains index pages used by Sphinx to
|
||||
generate the final content tree. Note that the REST API landing page used to
|
||||
render content in the generated website is found in the ``doc`` project.
|
||||
|
||||
For additional information on the API documentation, refer to :doc:`api_contribute_guide`.
|
||||
|
||||
******************
|
||||
Spec documentation
|
||||
******************
|
||||
|
||||
Spec documentation is found in the
|
||||
`Starlingx specs project <https://opendev.org/starlingx/specs>`_.
|
||||
|
||||
The ``specs/2019.03`` directory contains the documentation files for approved and
|
||||
implemented specs.
|
||||
|
||||
-----------------
|
||||
Updating a Manual
|
||||
-----------------
|
||||
-------------
|
||||
Writing style
|
||||
-------------
|
||||
|
||||
If you need to update an existing manual, you need to find the appropriate RST
|
||||
source file, make your modifications, test them (i.e. build the manual), and
|
||||
then submit the changes to Gerrit for approval.
|
||||
StarlingX documentation follows many (but not all!) of the writing style
|
||||
guidelines described in the `OpenStack documentation writing style guide <https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_. Differences
|
||||
between the StarlingX and OpenStack practices are highlighted below.
|
||||
|
||||
-----------------
|
||||
Creating a Manual
|
||||
-----------------
|
||||
* Use Title Case for page titles. For example:
|
||||
|
||||
Creating a new manual involves at minimum providing a new **index.rst** file.
|
||||
If the manual is more complex with additional content outside of the
|
||||
**index.rst** file, you need to provide additional RST files as well.
|
||||
::
|
||||
|
||||
As an example, consider a new manual that resides in **/doc/source/my-guide**.
|
||||
Furthermore, suppose this manual's **index.rst** file contained two
|
||||
links to additional complicated topics: "Topic 1" and
|
||||
"Topic 2".
|
||||
===============================
|
||||
Documentation Contributor Guide
|
||||
===============================
|
||||
|
||||
The content for the new manual exists in three files:
|
||||
* Start section titles with an action verb, but not a gerund (word that ends with -ing). For example:
|
||||
|
||||
* **/doc/source/my-guide/index.rst**
|
||||
* **/doc/source/my-guide/topic_1.rst**
|
||||
* **/doc/source/my-guide/topic_2.rst**
|
||||
::
|
||||
|
||||
Following shows the hierarchy:
|
||||
------------------
|
||||
Configure endpoint
|
||||
------------------
|
||||
|
||||
---------------
|
||||
RST conventions
|
||||
---------------
|
||||
|
||||
StarlingX documentation follows many (but not all!) of the RST conventions
|
||||
described in the `OpenStack documentation RST conventions guide <https://docs.openstack.org/doc-contrib-guide/rst-conv.html>`_. If RST markup is
|
||||
not listed in this section's quick reference, refer to the OpenStack guide.
|
||||
|
||||
For detailed information about RST and Sphinx extensions, refer to the following
|
||||
documents:
|
||||
|
||||
* `Sphinx documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
|
||||
* `reStructuredText primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
|
||||
|
||||
-------------------
|
||||
RST quick reference
|
||||
-------------------
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
********
|
||||
Acronyms
|
||||
********
|
||||
|
||||
Define acronym at first instance on page. After definition, use acronym only.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── my_guide
|
||||
│ │ ├── index.rst
|
||||
│ │ ├── topic_1.rst
|
||||
│ │ ├── topic_2.rst
|
||||
:abbr:`CPU (Central Processing Unit)`
|
||||
|
||||
**Output:**
|
||||
|
||||
-----------------------
|
||||
Creating the Index File
|
||||
-----------------------
|
||||
:abbr:`CPU (Central Processing Unit)`
|
||||
|
||||
The **index.rst** file provides captioning, a brief
|
||||
description of the document, and the table-of-contents (TOC) structure
|
||||
with instructions on how to display or hide sub-topics.
|
||||
************
|
||||
Code samples
|
||||
************
|
||||
|
||||
The syntax of the **index.rst** file is fixed. Following shows the
|
||||
sample **index.rst** file for the new guide:
|
||||
Format code snippets as standalone literal blocks.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
========
|
||||
My Guide
|
||||
========
|
||||
::
|
||||
|
||||
The new guide.
|
||||
ping 8.8.8.8
|
||||
|
||||
- :ref:`Topic 1 <topic_1>`
|
||||
- :ref:`Topic 2 <topic_2>`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
topic_1
|
||||
topic_2
|
||||
|
||||
Following are explanations for each of the four areas of the
|
||||
**index.rst** file:
|
||||
|
||||
- **Reference title:** Literal title that is used in the rendered
|
||||
document.
|
||||
In this case it is "My Guide".
|
||||
- **Reference summary:** Literal summary of the rendered document.
|
||||
In this case it is "The new guide."
|
||||
- **Table-of-Contents tree structure and sub-topic parameters:** The
|
||||
directive to create a TOC and to specify the embedded topic links
|
||||
should remain hidden.
|
||||
If you want sub-topics to be part of the TOC, use the
|
||||
":maxdepth: x" directive where "x" is the depth you desire for
|
||||
sub-topics in the TOC.
|
||||
- **RST source file root name:** The source files to use as content.
|
||||
In this case, the file references are "topic_1" and "topic_2".
|
||||
These reference the **topic_1.rst** and **topic_2.rst** files
|
||||
in the same folder as the **index.rst** file.
|
||||
|
||||
----------------------------------------------------
|
||||
Integrating the New Guide Into the Documentation Set
|
||||
----------------------------------------------------
|
||||
|
||||
The previous section described how you can provide the files
|
||||
you need to create a new guide.
|
||||
This section describes how to add your new guide to the table of contents in the
|
||||
documentation site.
|
||||
|
||||
The **/doc/source/index.rst** file contains the structure
|
||||
that defines the StarlingX Documentation landing page.
|
||||
Inside the file, is a "Sections" area that lists the documents
|
||||
that appear in the table of contents.
|
||||
Add your new guide to the toctree definition in the index.rst file.
|
||||
|
||||
--------------------------
|
||||
Closing Out a Bug or Story
|
||||
--------------------------
|
||||
|
||||
If you are modifying a document as a result of a defect or
|
||||
feature that is associated with a StoryBoard Story or Launchpad
|
||||
Bug, you must take steps to link your submission (Gerrit Review)
|
||||
to the story or bug.
|
||||
|
||||
To link a story, add the following lines in your
|
||||
commit message.
|
||||
Be sure to use the actual story ID and task ID with the commit:
|
||||
|
||||
* Story: $story_id
|
||||
* Task: $task_id
|
||||
|
||||
Following is an example that links a Gerrit Review with Story
|
||||
2003375 and Task 2444:
|
||||
**Output:**
|
||||
|
||||
::
|
||||
|
||||
Change the tox.ini directory regarding tox.ini dependencies
|
||||
ping 8.8.8.8
|
||||
|
||||
Story: 2003375
|
||||
Task: 24444
|
||||
********
|
||||
Commands
|
||||
********
|
||||
|
||||
**NOTE:** You must provide a blank line before the lines
|
||||
used to identify the Story and the Task.
|
||||
Furthermore, you must place these lines as the last lines
|
||||
in your commit message.
|
||||
If you do not follow these guidelines, your submission will not
|
||||
link to the Storyboard's story.
|
||||
Format commands using the Sphinx ``command`` role.
|
||||
|
||||
To link a bug, add the appropriate lines in your commit message.
|
||||
Be sure to provide the actual bug numbers:
|
||||
|
||||
* Closes-Bug: $bug_id
|
||||
* Partial-Bug: $bug_id
|
||||
* Related-Bug: $bug_id
|
||||
|
||||
If your fix requires multiple commits, use "Partial-Bug"
|
||||
for all the commits except the final one.
|
||||
For the final commit, use "Closes-Bug".
|
||||
|
||||
Following is an example commit message that closes out bug
|
||||
1804024:
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
AIO Hardware Requirements: Updated AIO HW requirements.
|
||||
:command:`system help`
|
||||
|
||||
Added Small HW form factor information simplex/duplex
|
||||
AIO hardware requirements.
|
||||
**Output:**
|
||||
|
||||
Closes-Bug: #1804024
|
||||
Use the :command:`system help` command for the full list of options.
|
||||
|
||||
When you associate a story or bug with a Gerrit review, Gerrit
|
||||
automatically updates the status of the story or bug once the
|
||||
commit is merged.
|
||||
Again, be sure to provide a blank line just before the line
|
||||
identifying the bug.
|
||||
****************
|
||||
Cross-references
|
||||
****************
|
||||
|
||||
You can find more information on the StarlingX code submission
|
||||
guidelines on the
|
||||
`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
|
||||
Cross-reference to arbitrary locations in a document using the ``ref`` role and a
|
||||
named target. Named targets must precede a section heading. For more information
|
||||
on references, see
|
||||
`Internal Hyperlink Targets <http://docutils.sourceforge.net/docs/user/rst/quickref.html#internal-hyperlink-targets>`_
|
||||
|
||||
To see the list of defects against StarlingX, see the
|
||||
`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
|
||||
|
||||
--------------------------
|
||||
Building the Documentation
|
||||
--------------------------
|
||||
|
||||
To build the documentation locally in HTML format, use the
|
||||
following command:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ tox -e docs
|
||||
|
||||
The resulting HTML files will be located in the **/doc/build**
|
||||
directory:
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
starlingx/docs/doc/
|
||||
├── build
|
||||
│ └── html
|
||||
.. _my_named_target:
|
||||
|
||||
----------------------------------
|
||||
Viewing the Rendered Documentation
|
||||
----------------------------------
|
||||
~~~~~~~~~~
|
||||
My section
|
||||
~~~~~~~~~~
|
||||
|
||||
To view the rendered documentation in a browser, open up
|
||||
the **index.html** file in your browser.
|
||||
This is the section we want to reference.
|
||||
|
||||
**NOTE:** The PDF build uses a different tox environment and is
|
||||
currently not supported for StarlingX.
|
||||
...
|
||||
|
||||
This is the reference to :ref:`my_named_target`.
|
||||
|
||||
**Output:**
|
||||
|
||||
.. _my_named_target:
|
||||
|
||||
~~~~~~~~~~
|
||||
My section
|
||||
~~~~~~~~~~
|
||||
|
||||
This is the section we want to reference.
|
||||
|
||||
...
|
||||
|
||||
This is the reference to :ref:`my_named_target`.
|
||||
|
||||
******************
|
||||
Information blocks
|
||||
******************
|
||||
|
||||
Emphasize information using notices (an 'admonition' in Sphinx). Different types of notices exist to emphasize degrees of information importance.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
.. note::
|
||||
|
||||
Use a ``note`` for a generic message.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Use ``seealso`` for extra but helpful information.
|
||||
|
||||
.. important::
|
||||
|
||||
Use ``important`` for details that can be easily missed, but should not be
|
||||
ignored by a user and are valuable before proceeding.
|
||||
|
||||
.. warning::
|
||||
|
||||
Use ``warning`` to call out information the user must understand
|
||||
to avoid negative consequences.
|
||||
|
||||
**Output:**
|
||||
|
||||
.. note::
|
||||
|
||||
Use a ``note`` for a generic message.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Use ``seealso`` for extra but helpful information.
|
||||
|
||||
.. important::
|
||||
|
||||
Use ``important`` for details that can be easily missed, but should not be
|
||||
ignored by a user and are valuable before proceeding.
|
||||
|
||||
.. warning::
|
||||
|
||||
Use ``warning`` to call out information the user must understand
|
||||
to avoid negative consequences.
|
||||
|
||||
|
||||
.. _starlingx/docs: https://opendev.org/starlingx/docs
|
||||
.. _starlingx/specs: https://opendev.org/starlingx/specs
|
||||
.. _starlingx/metal: https://opendev.org/starlingx/metal
|
||||
.. _starlingx/config: https://opendev.org/starlingx/config
|
||||
***************
|
||||
Inline elements
|
||||
***************
|
||||
|
||||
Format most inline elements such as filenames and paths, code fragments, parameters, or
|
||||
options with double back ticks.
|
||||
|
||||
**Input:**
|
||||
::
|
||||
|
||||
``/path/to/file.name``
|
||||
``--option``
|
||||
|
||||
**Output:**
|
||||
|
||||
Open the ``/path/to/file.name`` file.
|
||||
|
||||
Optionally pass the ``--option`` with the command.
|
||||
|
||||
Refer to the
|
||||
`OpenStack Inline elements guide <https://docs.openstack.org/doc-contrib-guide/rst-conv/inline-markups.html>`_
|
||||
for markup for other inline elements.
|
||||
|
||||
*****
|
||||
Lists
|
||||
*****
|
||||
|
||||
Use a bulleted list for a sequence of items whose order does not matter, such as a list of features.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
* Banana
|
||||
* Apple
|
||||
* Orange
|
||||
|
||||
**Output:**
|
||||
|
||||
* Banana
|
||||
* Apple
|
||||
* Orange
|
||||
|
||||
Use an enumerated list for a sequence of items whose order matters, such as in an ordered sequence of installation steps.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
#. Wash apple.
|
||||
#. Peel apple.
|
||||
#. Eat apple.
|
||||
|
||||
**Output:**
|
||||
|
||||
#. Wash apple.
|
||||
#. Peel apple.
|
||||
#. Eat apple.
|
||||
|
||||
Use a definition list for an unordered list where each item has a short definition, such as term/definition pairs.
|
||||
|
||||
**Input:**
|
||||
|
||||
::
|
||||
|
||||
Command A
|
||||
Description of command A.
|
||||
|
||||
Command B
|
||||
Description of command B.
|
||||
|
||||
**Output:**
|
||||
|
||||
Command A
|
||||
Description of command A.
|
||||
|
||||
Command B
|
||||
Description of command B.
|
||||
|
||||
****************
|
||||
Section headings
|
||||
****************
|
||||
|
||||
Use up to three levels of headings in one file using the following characters:
|
||||
|
||||
* Heading 1 (Page Title in Title Case) - underline and overline with equal signs;
|
||||
|
||||
* Heading 2 (Major page sections in Sentence case) - underline and overline with dashes;
|
||||
|
||||
* Heading 3 (subsections in Sentence case) - underline and overline with asterisks.
|
||||
|
||||
Example RST:
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
==============
|
||||
Document Title
|
||||
==============
|
||||
|
||||
Introduce the topic using 1-2 concise sentences. It should tell the user what
|
||||
info can be found on this page.
|
||||
|
||||
.. contents:: // Use a local TOC to aid user navigation in the page
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
---------------
|
||||
Section heading
|
||||
---------------
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
******************
|
||||
Subsection heading
|
||||
******************
|
||||
|
||||
Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula nunc hendrerit magna, nec tristique ex tortor non lorem.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +1,13 @@
|
|||
.. _contribute:
|
||||
|
||||
==========
|
||||
Contribute
|
||||
==========
|
||||
==================
|
||||
Contributor Guides
|
||||
==================
|
||||
|
||||
The following guides provide detailed instructions on the contribution workflow
|
||||
and conventions to be considered when contributing to the StarlingX documentation.
|
||||
Welcome to the StarlingX community! We are glad you are here.
|
||||
|
||||
StarlingX utilizes tooling and CI/CD environments from the OpenStack
|
||||
Foundation. The source is hosted on `OpenDev's Git server`_.
|
||||
|
||||
.. _`OpenDev's Git server`: https://opendev.org/starlingx
|
||||
If you are new to the project, take a moment to review the
|
||||
`StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_.
|
||||
|
||||
---------------------------
|
||||
Contribute to documentation
|
||||
|
|
@ -19,43 +16,26 @@ Contribute to documentation
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
doc_contribute_guide
|
||||
api_contribute_guide
|
||||
release_note_contribute_guide
|
||||
doc_contribute_guide
|
||||
|
||||
-------------------
|
||||
Development process
|
||||
-------------------
|
||||
------------------
|
||||
Contribute to code
|
||||
------------------
|
||||
|
||||
For information on the StarlingX development process, refer to the following guide:
|
||||
StarlingX follows the
|
||||
`OpenStack developer contribution guidelines <https://docs.openstack.org/infra/manual/developers.html>`_. Additional StarlingX-specific resources are listed below.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
development_process
|
||||
|
||||
---------------
|
||||
Build StarlingX
|
||||
---------------
|
||||
|
||||
Refer to the StarlingX Build Guide for instructions on how to build a StarlingX
|
||||
ISO image.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
build_guide
|
||||
Code Submission Guidelines <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>
|
||||
|
||||
--------------------
|
||||
Additional resources
|
||||
--------------------
|
||||
|
||||
Additional information about contributing to OpenStack documentation can be found
|
||||
in the following guides:
|
||||
|
||||
* `OpenStack API documentation guide`_
|
||||
* `OpenStack Documentation Contributor Guide`_
|
||||
|
||||
.. _`OpenStack Documentation Contributor Guide`: https://docs.openstack.org/doc-contrib-guide/index.html
|
||||
|
||||
.. _`OpenStack API documentation guide`: https://docs.openstack.org/doc-contrib-guide/api-guides.html
|
||||
* `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_
|
||||
* :doc:`/developer_resources/index`
|
||||
|
|
@ -1,41 +1,44 @@
|
|||
===============================
|
||||
Release notes contributor guide
|
||||
Release Notes Contributor Guide
|
||||
===============================
|
||||
|
||||
Release notes for StarlingX projects are managed using Reno allowing release
|
||||
notes go through the same review process used for managing code changes.
|
||||
Release documentation information comes from YAML source files stored in the
|
||||
project repository, that when built in conjuction with RST source files,
|
||||
project repository, that when built in conjunction with RST source files,
|
||||
generate HTML files. More details about the Reno Release Notes Manager can
|
||||
be found at: https://docs.openstack.org/reno
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
---------
|
||||
Locations
|
||||
---------
|
||||
|
||||
StarlingX release notes documentation exists in the following projects:
|
||||
|
||||
- `starlingx/clients`_: StarlingX Client Libraries
|
||||
- `starlingx/config`_: StarlingX System Configuration Management
|
||||
- `starlingx/distcloud`_: StarlingX Distributed Cloud
|
||||
- `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client
|
||||
- `starlingx/fault`_: StarlingX Fault Management
|
||||
- `starlingx/gui`_: StarlingX Horizon plugins for new StarlingX services
|
||||
- `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management
|
||||
- `starlingx/integ`_: StarlingX Integration and Packaging
|
||||
- `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance
|
||||
- `starlingx/nfv`_: StarlingX NFVI Orchestration
|
||||
- `starlingx/tools`_: StarlingX Build Tools
|
||||
- `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore
|
||||
- `starlingx/upstream`_: StarlingX Upstream Packaging
|
||||
* `starlingx/clients`_: StarlingX Client Libraries
|
||||
* `starlingx/config`_: StarlingX System Configuration Management
|
||||
* `starlingx/distcloud`_: StarlingX Distributed Cloud
|
||||
* `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client
|
||||
* `starlingx/fault`_: StarlingX Fault Management
|
||||
* `starlingx/gui`_: StarlingX Horizon plugins for new StarlingX services
|
||||
* `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management
|
||||
* `starlingx/integ`_: StarlingX Integration and Packaging
|
||||
* `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance
|
||||
* `starlingx/nfv`_: StarlingX NFVI Orchestration
|
||||
* `starlingx/tools`_: StarlingX Build Tools
|
||||
* `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore
|
||||
* `starlingx/upstream`_: StarlingX Upstream Packaging
|
||||
|
||||
--------------------
|
||||
Directory Structures
|
||||
Directory structures
|
||||
--------------------
|
||||
|
||||
The directory structure of release documentation under each StarlingX project
|
||||
repository is fixed. Here is an example showing **stx-confi** StarlingX System
|
||||
Configuration Management:
|
||||
repository is fixed. This example shows the ``stx-confi`` project:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -51,23 +54,35 @@ Configuration Management:
|
|||
The initial modifications and additions to enable the API Documentation service
|
||||
in each StarlingX project are as follows:
|
||||
|
||||
- **.gitignore** modifications to ignore the building directories and HTML files
|
||||
for the Release Notes
|
||||
- **.zuul.yaml** modifications to add the jobs to build and publish the api-ref
|
||||
document
|
||||
- **releasenotes/notes/** directory creation to store your release notes files
|
||||
in YAML format
|
||||
- **releasenotes/source** directory creation to store your API Reference project
|
||||
directory
|
||||
- **releasenotes/source/conf.py** configuration file to determine the HTML theme,
|
||||
Sphinx extensions and project information
|
||||
- **releasenotes/source/index.rst** source file to create your index RST source
|
||||
file
|
||||
- **releasenotes/source/unrelased.rst** source file to avoid breaking the real
|
||||
release notes build job on the master branch
|
||||
- **doc/requiremets.txt** modifications to add the os-api-ref Sphinx extension
|
||||
- **tox.ini** modifications to add the configuration to build the API reference
|
||||
locally
|
||||
``.gitignore``
|
||||
Modifications to ignore the building directories and HTML files for the
|
||||
release notes.
|
||||
|
||||
``.zuul.yaml``
|
||||
Modifications to add jobs to build and publish the ``api-ref`` document.
|
||||
|
||||
``releasenotes/notes``
|
||||
Directory created to store your release notes files in YAML format.
|
||||
|
||||
``releasenotes/source``
|
||||
Directory created to store your API reference project directory.
|
||||
|
||||
``releasenotes/source/conf.py``
|
||||
Configuration file to determine the HTML theme, Sphinx extensions, and
|
||||
project information.
|
||||
|
||||
``releasenotes/source/index.rst``
|
||||
Source file to create your index RST source file.
|
||||
|
||||
``releasenotes/source/unrelased.rst``
|
||||
Source file to avoid breaking the real release notes build job on the master
|
||||
branch.
|
||||
|
||||
``doc/requiremets.txt``
|
||||
Modifications to add the ``os-api-ref`` Sphinx extension.
|
||||
|
||||
``tox.ini``
|
||||
Modifications to add the configuration to build the API reference locally.
|
||||
|
||||
See stx-config [Doc] Release Notes Management as an example of this first commit:
|
||||
https://review.opendev.org/#/c/603257/
|
||||
|
|
@ -76,11 +91,11 @@ Once the Release Notes Documentation service has been enabled, you can create a
|
|||
release notes.
|
||||
|
||||
-------------------
|
||||
Release Notes Files
|
||||
Release notes files
|
||||
-------------------
|
||||
|
||||
The following shows the YAML source file for the stx-config StarlingX System
|
||||
Configuration Management:
|
||||
The following shows the YAML source file for the stx-config project:
|
||||
|
||||
`Release Summary R1.0 <http://git.openstack.org/cgit/openstack/stx-config/tree/releasenotes/notes/release-summary-6738ff2f310f9b57.yaml>`_
|
||||
|
||||
::
|
||||
|
|
@ -89,12 +104,12 @@ Configuration Management:
|
|||
├── notes
|
||||
│ └── release-summary-6738ff2f310f9b57.yaml
|
||||
|
||||
|
||||
To create a new release note that document your code changes via tox newnote environment:
|
||||
To create a new release note that documents your code changes via the
|
||||
tox newnote environment:
|
||||
|
||||
$ tox -e newnote hello-my-change
|
||||
|
||||
A YAML source file is created with a unique name under releasenote/notes/ directory:
|
||||
A YAML source file is created with a unique name under ``releasenote/notes/`` directory:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -102,7 +117,7 @@ A YAML source file is created with a unique name under releasenote/notes/ direct
|
|||
├── notes
|
||||
│ ├── hello-my-change-dcef4b934a670160.yaml
|
||||
|
||||
The content are gound into logical sections based in the default template used by reno:
|
||||
The content is grouped into logical sections based in the default template used by reno:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -118,75 +133,8 @@ The content are gound into logical sections based in the default template used b
|
|||
Modify the content in the YAML source file based on
|
||||
`reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_ format.
|
||||
|
||||
--------------------------
|
||||
Closing Out a Bug or Story
|
||||
--------------------------
|
||||
|
||||
If you are modifying a document as a result of a defect or
|
||||
feature that is associated with a StoryBoard Story or Launchpad
|
||||
Bug, you must take steps to link your submission (Gerrit Review)
|
||||
to the story or bug.
|
||||
|
||||
To link a story, add the following lines in your
|
||||
commit message.
|
||||
Be sure to use the actual story ID and task ID with the commit:
|
||||
|
||||
* Story: $story_id
|
||||
* Task: $task_id
|
||||
|
||||
Following is an example that links a Gerrit Review with Story
|
||||
2003375 and Task 2444:
|
||||
|
||||
::
|
||||
|
||||
Change the tox.ini directory regarding tox.ini dependencies
|
||||
|
||||
Story: 2003375
|
||||
Task: 24444
|
||||
|
||||
**NOTE:** You must provide a blank line before the lines
|
||||
used to identify the story and the task.
|
||||
If you do not provide this line, your submission will not
|
||||
link to the Storyboard's story.
|
||||
|
||||
To link a bug, add the approprite lines in your commit message.
|
||||
Be sure to provide the actual bug numbers:
|
||||
|
||||
* Closes-Bug: $bug_id
|
||||
* Partial-Bug: $bug_id
|
||||
* Related-Bug: $bug_id
|
||||
|
||||
If your fix requires multiple commits, use "Partial-Bug"
|
||||
for all the commits except the final one.
|
||||
For the final commit, use "Closes-Bug".
|
||||
|
||||
Following is an example commit message that closes out bug
|
||||
1804024:
|
||||
|
||||
::
|
||||
|
||||
AIO Hardware Requirements: Updated AIO HW requirements.
|
||||
|
||||
Added Small HW form factor information simplex/duplex
|
||||
AIO hardware requirements.
|
||||
|
||||
Closes-Bug: #1804024
|
||||
|
||||
When you associate a story or bug with a Gerrit review, Gerrit
|
||||
automatically updates the status of the story or bug once the
|
||||
commit is merged.
|
||||
Again, be sure to provide a blank line just before the line
|
||||
identifying the bug.
|
||||
|
||||
You can find more information on the StarlingX code submission
|
||||
guidelines on the
|
||||
`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
|
||||
|
||||
To see the list of defects against StarlingX, see the
|
||||
`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
|
||||
|
||||
------------------
|
||||
Developer Workflow
|
||||
Developer workflow
|
||||
------------------
|
||||
|
||||
#. Start common development workflow to create your change: "Hello My Change".
|
||||
|
|
@ -195,7 +143,7 @@ Developer Workflow
|
|||
#. Add your change including its release notes and submit for review.
|
||||
|
||||
---------------------
|
||||
Release Team Workflow
|
||||
Release team workflow
|
||||
---------------------
|
||||
|
||||
#. Start development work to prepare the release. This might include a
|
||||
|
|
@ -203,8 +151,6 @@ Release Team Workflow
|
|||
#. Generate the Reno Report.
|
||||
#. Add your change and submit for review.
|
||||
|
||||
|
||||
|
||||
.. _starlingx/clients: https://opendev.org/starlingx/clients
|
||||
.. _starlingx/config: https://opendev.org/starlingx/config
|
||||
.. _starlingx/distcloud: https://opendev.org/starlingx/distcloud
|
||||
|
|
|
|||
|
|
@ -250,7 +250,7 @@ Unload firewall and disable firewall on boot:
|
|||
Getting the StarlingX ISO image
|
||||
-------------------------------
|
||||
|
||||
Follow the instructions from the :doc:`/contributor/build_guide` to build a
|
||||
Follow the instructions from the :doc:`/developer_resources/build_guide` to build a
|
||||
StarlingX ISO image.
|
||||
|
||||
**********
|
||||
|
|
|
|||
|
|
@ -2,7 +2,12 @@
|
|||
StarlingX Build Guide
|
||||
=====================
|
||||
|
||||
This section describes the steps for building an ISO image from a StarlingX release.
|
||||
This section describes the steps for building an ISO image from a StarlingX
|
||||
release.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
------------
|
||||
Requirements
|
||||
|
|
@ -4,13 +4,10 @@
|
|||
Developer Resources
|
||||
===================
|
||||
|
||||
StarlingX developer resources provide information to help you understand the
|
||||
architecture of the documentation, how to navigate the StarlingX
|
||||
source code, and to understand the development process.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
build_guide
|
||||
navigate_source_code
|
||||
architecture_docs
|
||||
starlingx_patching
|
||||
|
|
|
|||
Loading…
Reference in New Issue