starlingx/docs
Code Issues Proposed changes

Update and simplification of contribution guides

Browse Source 
- 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
2019-12-13 14:47:08 -08:00
parent d1c9155684
commit 20269cc03f
8 changed files with 547 additions and 536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
doc/source/contributor/api_contribute_guide.rst
View File

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

799
doc/source/contributor/build_guide.rst
View File

@@ -1,799 +0,0 @@
=====================
StarlingX Build Guide
=====================
This section describes the steps for building an ISO image from a StarlingX release.
------------
Requirements
------------
*********************
Hardware requirements
*********************
A workstation computer with:
* Processor: x86_64 is the only supported architecture
* Memory: At least 32GB RAM
* Hard Disk: 500GB HDD
* Network: Network adapter with active Internet connection
*********************
Software requirements
*********************
A workstation computer with:
* Operating System: Ubuntu 16.04 LTS 64-bit
* Docker
* Android Repo Tool
* Proxy settings configured, if required (See
http://lists.starlingx.io/pipermail/starlingx-discuss/2018-July/000136.html for more details)
* Public SSH key
-----------------------------
Development environment setup
-----------------------------
This section describes how to set up a StarlingX development system on a
workstation computer. After completing these steps, you can build a StarlingX
ISO image on the following Linux distribution:
* Ubuntu 16.04 LTS 64-bit
****************************
Update your operating system
****************************
Before proceeding with the build, ensure your Ubuntu distribution is up to date.
You first need to update the local database list of available packages:
::
sudo apt-get update
******************************************
Installation requirements and dependencies
******************************************
#. Set up <user>.
Make sure you are a non-root user with sudo privileges enabled when you build
the StarlingX ISO.
Use either your existing user or create a separate *<user>*:
::
sudo useradd -m -d /home/<user> <user>
sudo sh -c "echo '<user> ALL=(ALL:ALL) ALL' >> /etc/sudoers"
sudo su -c <user>
#. Set up Git.
Install the required Git packages on the Ubuntu host system:
::
sudo apt-get install make git curl
Set up your identity in git using your actual name and email address:
::
git config --global user.name "Name LastName"
git config --global user.email "Email Address"
#. Install the required Docker CE packages in the Ubuntu host system.
See
`Get Docker CE for Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/#os-requirements>`__ for more information.
Make sure to log out and log in to add your *<user>* to the Docker group:
::
sudo usermod -aG docker <user>
#. Install the Android Repo Tool in the Ubuntu host system.
Follow the steps in the
`Installing Repo <https://source.android.com/setup/build/downloading#installing-repo>`__
section.
**********************
Install public SSH key
**********************
Follow these instructions on GitHub to
`Generate a Public SSH Key <https://help.github.com/articles/connecting-to-github-with-ssh>`__.
Then upload your public key to your GitHub and Gerrit account profiles:
* `Upload to Github <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account>`__
* `Upload to Gerrit <https://review.opendev.org/#/settings/ssh-keys>`__
****************************
Create a workspace directory
****************************
Create a *starlingx* workspace directory on your system. Best practices dictate
creating the workspace directory in your $HOME directory:
::
mkdir -p $HOME/starlingx/
*********************
Install tools project
*********************
#. Under your $HOME directory, clone the <tools> project:
::
cd $HOME
git clone https://opendev.org/starlingx/tools.git
#. Navigate to the *<$HOME/tools>* project
directory:
::
cd $HOME/tools/
-----------------------------
Prepare the base Docker image
-----------------------------
StarlingX base Docker image handles all steps related to StarlingX ISO
creation. This section describes how to customize the base Docker image
building process.
********************
Configuration values
********************
You can customize values for the StarlingX base Docker image using a
text-based configuration file named ``localrc``:
* ``HOST_PREFIX`` points to the directory that hosts the 'designer'
subdirectory for source code, the 'loadbuild' subdirectory for
the build environment, generated RPMs, and the ISO image.
* ``HOST_MIRROR_DIR`` points to the directory that hosts the CentOS mirror
repository.
^^^^^^^^^^^^^^^^^^^^^^^^^^
localrc configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^
Create your ``localrc`` configuration file. For example:
::
# tbuilder localrc
MYUNAME=<your user name>
PROJECT=starlingx
HOST_PREFIX=$HOME/starlingx/workspace
HOST_MIRROR_DIR=$HOME/starlingx/mirror
***************************
Build the base Docker image
***************************
Once the ``localrc`` configuration file has been customized, it is time
to build the base Docker image.
#. If necessary, you might have to set http/https proxy in your
Dockerfile before building the docker image:
::
ENV http_proxy " http://your.actual_http_proxy.com:your_port "
ENV https_proxy " https://your.actual_https_proxy.com:your_port "
ENV ftp_proxy " http://your.actual_ftp_proxy.com:your_port "
RUN echo " proxy=http://your-proxy.com:port " >> /etc/yum.conf
#. The ``tb.sh`` script automates the base Docker image build:
::
./tb.sh create
----------------------------------
Build the CentOS mirror repository
----------------------------------
The creation of the StarlingX ISO relies on a repository of RPM binaries,
RPM sources, and tar compressed files. This section describes how to build
this CentOS mirror repository.
*******************************
Run repository Docker container
*******************************
Run the following commands under a terminal identified as "**One**":
#. Navigate to the *$HOME/tools/centos-mirror-tool* project
directory:
::
cd $HOME/tools/centos-mirror-tools/
#. Launch the Docker container using the previously created base Docker image
*<repository>:<tag>*. As /localdisk is defined as the workdir of the
container, you should use the same folder name to define the volume.
The container starts to run and populate 'logs' and 'output' folders in
this directory. The container runs from the same directory in which the
scripts are stored.
::
docker run -it --volume $(pwd):/localdisk local/$USER-stx-builder:7.4 bash
*****************
Download packages
*****************
#. Inside the Docker container, enter the following commands to download
the required packages to populate the CentOS mirror repository:
::
cd localdisk && bash download_mirror.sh
#. Monitor the download of packages until it is complete. When the download
is complete, the following message appears:
::
totally 17 files are downloaded!
step #3: done successfully
IMPORTANT: The following 3 files are just bootstrap versions. Based on them, the workable images
for StarlingX could be generated by running "update-pxe-network-installer" command after "build-iso"
- out/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img
- out/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img
- out/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz
***************
Verify packages
***************
#. Verify no missing or failed packages exist:
::
cat logs/*_missing_*.log
cat logs/*_failmoved_*.log
#. In case missing or failed packages do exist, which is usually caused by
network instability (or timeout), you need to download the packages
manually.
Doing so assures you get all RPMs listed in
*rpms_3rdparties.lst*/*rpms_centos.lst*/*rpms_centos3rdparties.lst*.
******************
Packages structure
******************
The following is a general overview of the packages structure resulting
from downloading the packages:
::
/home/<user>/tools/centos-mirror-tools/output
└── stx-r1
└── CentOS
└── pike
├── Binary
│   ├── EFI
│   ├── images
│   ├── isolinux
│   ├── LiveOS
│   ├── noarch
│   └── x86_64
├── downloads
│   ├── integrity
│   └── puppet
└── Source
*******************************
Create CentOS mirror repository
*******************************
Outside your Repository Docker container, in another terminal identified
as "**Two**", run the following commands:
#. From terminal identified as "**Two**", create a *mirror/CentOS*
directory under your *starlingx* workspace directory:
::
mkdir -p $HOME/starlingx/mirror/CentOS/
#. Copy the built CentOS mirror repository built under
*$HOME/tools/centos-mirror-tool* to the *$HOME/starlingx/mirror/*
workspace directory:
::
cp -r $HOME/tools/centos-mirror-tools/output/stx-r1/ $HOME/starlingx/mirror/CentOS/
-------------------------
Create StarlingX packages
-------------------------
*****************************
Run building Docker container
*****************************
#. From the terminal identified as "**Two**", create the workspace folder:
::
mkdir -p $HOME/starlingx/workspace
#. Navigate to the *$HOME/tools* project directory:
::
cd $HOME/tools
#. Verify environment variables:
::
bash tb.sh env
#. Run the building Docker container:
::
bash tb.sh run
#. Execute the buiding Docker container:
::
bash tb.sh exec
*********************************
Download source code repositories
*********************************
#. From the terminal identified as "**Two**", which is now inside the
building Docker container, start the internal environment:
::
eval $(ssh-agent)
ssh-add
#. Use the repo tool to create a local clone of the manifest
Git repository based on the "master" branch:
::
cd $MY_REPO_ROOT_DIR
repo init -u https://opendev.org/starlingx/manifest -m default.xml
Optionally, specify a specific branch to clone, for example the R2.0 release
branch:
::
cd $MY_REPO_ROOT_DIR
repo init -u https://opendev.org/starlingx/manifest -m default.xml -b r/stx.2.0
#. Synchronize the repository:
::
repo sync -j`nproc`
#. Create a tarballs repository:
::
ln -s /import/mirrors/CentOS/stx-r1/CentOS/pike/downloads/ $MY_REPO/stx/
Alternatively, you can run the "populate_downloads.sh" script to copy
the tarballs instead of using a symlink:
::
populate_downloads.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
Outside the container
#. From another terminal identified as "**Three**", create mirror binaries:
::
mkdir -p $HOME/starlingx/mirror/CentOS/stx-installer
cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img $HOME/starlingx/mirror/CentOS/stx-installer/initrd.img
cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz $HOME/starlingx/mirror/CentOS/stx-installer/vmlinuz
cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img $HOME/starlingx/mirror/CentOS/stx-installer/squashfs.img
**************
Build packages
**************
#. Go back to the terminal identified as "**Two**", which is the building
Docker container.
#. **Temporal!** Build-Pkgs Errors. Be prepared to have some missing /
corrupted rpm and tarball packages generated during
`Build the CentOS Mirror Repository`_, which will cause the next step
to fail. If that step does fail, manually download those missing /
corrupted packages.
#. Update the symbolic links:
::
generate-cgcs-centos-repo.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
#. Build the packages:
::
build-pkgs
#. **Optional!** Generate-Cgcs-Tis-Repo:
While this step is optional, it improves performance on subsequent
builds. The cgcs-tis-repo has the dependency information that
sequences the build order. To generate or update the information, you
need to execute the following command after building modified or new
packages.
::
generate-cgcs-tis-repo
-------------------
Build StarlingX ISO
-------------------
Build the image:
::
build-iso
---------------
Build installer
---------------
To get your StarlingX ISO ready to use, you must create the initialization
files used to boot the ISO, additional controllers, and compute nodes.
**NOTE:** You only need this procedure during your first build and
every time you upgrade the kernel.
After running "build-iso", run:
::
build-pkgs --installer
This builds *rpm* and *anaconda* packages. Then run:
::
update-pxe-network-installer
The *update-pxe-network-installer* covers the steps detailed in
*$MY_REPO/stx/stx-metal/installer/initrd/README*. This script
creates three files on
*/localdisk/loadbuild/pxe-network-installer/output*.
::
new-initrd.img
new-squashfs.img
new-vmlinuz
Rename the files as follows:
::
initrd.img
squashfs.img
vmlinuz
Two ways exist for using these files:
#. Store the files in the */import/mirror/CentOS/stx-installer/* folder
for future use.
#. Store the files in an arbitrary location and modify the
*$MY_REPO/stx/stx-metal/installer/pxe-network-installer/centos/build_srpm.data*
file to point to these files.
Recreate the *pxe-network-installer* package and rebuild the image:
::
build-pkgs --clean pxe-network-installer
build-pkgs pxe-network-installer
build-iso
Your ISO image should be able to boot.
****************
Additional notes
****************
* In order to get the first boot working, this complete procedure needs to be
done. However, once the init files are created, these can be stored in a shared location where different developers can make use of them. Updating these files
is not a frequent task and should be done whenever the kernel is upgraded.
* StarlingX is in active development. Consequently, it is possible that a
future version will change to a more generic solution.
---------------
Build avoidance
---------------
*******
Purpose
*******
Greatly reduce build times after using "repo" to syncronized a local repository
with an upstream source (i.e. "repo sync"). Build avoidance works well for
designers working within a regional office. Starting from a new workspace,
"build-pkgs" typically requires three or more hours to complete. Build avoidance
reduces this step to approximately 20 minutes.
***********
Limitations
***********
* Little or no benefit for designers who refresh a pre-existing workspace at
least daily (e.g. download_mirror.sh, repo sync, generate-cgcs-centos-repo.sh, build-pkgs, build-iso). In these cases, an incremental build (i.e. reuse of
same workspace without a :command:`build-pkgs --clean`) is often just as
efficient.
* Not likely to be useful to solo designers, or teleworkers that wish to compile
on using their home computers. Build avoidance downloads build artifacts from a reference build, and WAN speeds are generally too slow.
*****************
Method (in brief)
*****************
#. Reference builds
* A server in the regional office performs regular (e.g. daily) automated
builds using existing methods. These builds are called "reference builds".
* The builds are timestamped and preserved for some time (i.e. a number of weeks).
* A build CONTEXT, which is a file produced by "build-pkgs" at location
*$MY_WORKSPACE/CONTEXT*, is captured. It is a bash script that can cd to
each and every Git and checkout the SHA that contributed to the build.
* For each package built, a file captures the md5sums of all the source code
inputs required to build that package. These files are also produced by
"build-pkgs" at location *$MY_WORKSPACE//rpmbuild/SOURCES//srpm_reference.md5*.
* All these build products are accessible locally (e.g. a regional office)
using "rsync".
**NOTE:** Other protocols can be added later.
#. Designers
* Request a build avoidance build. Recommended after you have
done synchronized the repository (i.e. "repo sync").
::
repo sync
generate-cgcs-centos-repo.sh
populate_downloads.sh
build-pkgs --build-avoidance
* Use combinations of additional arguments, environment variables, and a
configuration file unique to the regional office to specify an URL
to the reference builds.
* Using a configuration file to specify the location of your reference build:
::
mkdir -p $MY_REPO/local-build-data
cat <<- EOF > $MY_REPO/local-build-data/build_avoidance_source
# Optional, these are already the default values.
BUILD_AVOIDANCE_DATE_FORMAT="%Y%m%d"
BUILD_AVOIDANCE_TIME_FORMAT="%H%M%S"
BUILD_AVOIDANCE_DATE_TIME_DELIM="T"
BUILD_AVOIDANCE_DATE_TIME_POSTFIX="Z"
BUILD_AVOIDANCE_DATE_UTC=1
BUILD_AVOIDANCE_FILE_TRANSFER="rsync"
# Required, unique values for each regional office
BUILD_AVOIDANCE_USR="jenkins"
BUILD_AVOIDANCE_HOST="stx-builder.mycompany.com"
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
EOF
* Using command-line arguments to specify the location of your reference
build:
::
build-pkgs --build-avoidance --build-avoidance-dir /localdisk/loadbuild/jenkins/StarlingX_Reference_Build --build-avoidance-host stx-builder.mycompany.com --build-avoidance-user jenkins
* Prior to your build attempt, you need to accept the host key. Doing so
prevents "rsync" failures on a "yes/no" prompt. You only have to do this once.
::
grep -q $BUILD_AVOIDANCE_HOST $HOME/.ssh/known_hosts
if [ $? != 0 ]; then
ssh-keyscan $BUILD_AVOIDANCE_HOST >> $HOME/.ssh/known_hosts
fi
* "build-pkgs" does the following:
* From newest to oldest, scans the CONTEXTs of the various reference builds.
Selects the first (i.e. most recent) context that satisfies the following
requirement: every Git the SHA specifies in the CONTEXT is present.
* The selected context might be slightly out of date, but not by more than
a day. This assumes daily reference builds are run.
* If the context has not been previously downloaded, then download it now.
This means you need to download select portions of the reference build
workspace into the designer's workspace. This includes all the SRPMS,
RPMS, MD5SUMS, and miscellaneous supporting files. Downloading these files
usually takes about 10 minutes over an office LAN.
* The designer could have additional commits or uncommitted changes not
present in the reference builds. Affected packages are identified by the
differing md5sum's. In these cases, the packages are re-built. Re-builds
usually take five or more minutes, depending on the packages that have changed.
* What if no valid reference build is found? Then build-pkgs will fall back
to a regular build.
****************
Reference builds
****************
* The regional office implements an automated build that pulls the latest
StarlingX software and builds it on a regular basis (e.g. daily builds).
Jenkins, cron, or similar tools can trigger these builds.
* Each build is saved to a unique directory, and preserved for a time that is
reflective of how long a designer might be expected to work on a private branch
without syncronizing with the master branch. This takes about two weeks.
* The *MY_WORKSPACE* directory for the build shall have a common root
directory, and a leaf directory that is a sortable time stamp. The
suggested format is *YYYYMMDDThhmmss*.
::
sudo apt-get update
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ')
MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP}
* Designers can access all build products over the internal network of the
regional office. The current prototype employs "rsync". Other protocols that
can efficiently share, copy, or transfer large directories of content can be
added as needed.
^^^^^^^^^^^^^^
Advanced usage
^^^^^^^^^^^^^^
Can the reference build itself use build avoidance? Yes it can.
Can it reference itself? Yes it can.
In both these cases, caution is advised. To protect against any possible
'divergence from reality', you should limit how many steps you remove
a build avoidance build from a full build.
Suppose we want to implement a self-referencing daily build in an
environment where a full build already occurs every Saturday.
To protect ourselves from a
build failure on Saturday we also want a limit of seven days since
the last full build. Your build script might look like this ...
::
...
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
BUILD_AVOIDANCE_HOST="stx-builder.mycompany.com"
FULL_BUILD_DAY="Saturday"
MAX_AGE_DAYS=7
LAST_FULL_BUILD_LINK="$BUILD_AVOIDANCE_DIR/latest_full_build"
LAST_FULL_BUILD_DAY=""
NOW_DAY=$(date -u "+%A")
BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ')
MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP}
# update software
repo init -u ${BUILD_REPO_URL} -b ${BUILD_BRANCH}
repo sync --force-sync
$MY_REPO_ROOT_DIR/tools/toCOPY/generate-cgcs-centos-repo.sh
$MY_REPO_ROOT_DIR/tools/toCOPY/populate_downloads.sh
# User can optionally define BUILD_METHOD equal to one of 'FULL', 'AVOIDANCE', or 'AUTO'
# Sanitize BUILD_METHOD
if [ "$BUILD_METHOD" != "FULL" ] && [ "$BUILD_METHOD" != "AVOIDANCE" ]; then
BUILD_METHOD="AUTO"
fi
# First build test
if [ "$BUILD_METHOD" != "FULL" ] && [ ! -L $LAST_FULL_BUILD_LINK ]; then
echo "latest_full_build symlink missing, forcing full build"
BUILD_METHOD="FULL"
fi
# Build day test
if [ "$BUILD_METHOD" == "AUTO" ] && [ "$NOW_DAY" == "$FULL_BUILD_DAY" ]; then
echo "Today is $FULL_BUILD_DAY, forcing full build"
BUILD_METHOD="FULL"
fi
# Build age test
if [ "$BUILD_METHOD" != "FULL" ]; then
LAST_FULL_BUILD_DATE=$(basename $(readlink $LAST_FULL_BUILD_LINK) | cut -d '_' -f 1)
LAST_FULL_BUILD_DAY=$(date -d $LAST_FULL_BUILD_DATE "+%A")
AGE_SECS=$(( $(date "+%s") - $(date -d $LAST_FULL_BUILD_DATE "+%s") ))
AGE_DAYS=$(( $AGE_SECS/60/60/24 ))
if [ $AGE_DAYS -ge $MAX_AGE_DAYS ]; then
echo "Haven't had a full build in $AGE_DAYS days, forcing full build"
BUILD_METHOD="FULL"
fi
BUILD_METHOD="AVOIDANCE"
fi
#Build it
if [ "$BUILD_METHOD" == "FULL" ]; then
build-pkgs --no-build-avoidance
else
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER
fi
if [ $? -ne 0 ]; then
echo "Build failed in build-pkgs"
exit 1
fi
build-iso
if [ $? -ne 0 ]; then
echo "Build failed in build-iso"
exit 1
fi
if [ "$BUILD_METHOD" == "FULL" ]; then
# A successful full build. Set last full build symlink.
if [ -L $LAST_FULL_BUILD_LINK ]; then
rm -rf $LAST_FULL_BUILD_LINK
fi
ln -sf $MY_WORKSPACE $LAST_FULL_BUILD_LINK
fi
...
A final note....
To use the full build day as your avoidance build reference point,
modify the "build-pkgs" commands above to use "--build-avoidance-day ",
as shown in the following two examples:
::
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER --build-avoidance-day $FULL_BUILD_DAY
# Here is another example with a bit more shuffling of the above script.
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER --build-avoidance-day $LAST_FULL_BUILD_DAY
The advantage is that our build is never more than one step removed
from a full build. This assumes the full build was successful.
The disadvantage is that by the end of the week, the reference build is getting
rather old. During active weeks, build times could approach build times for
full builds.

4
doc/source/contributor/development_process.rst
View File

@@ -2,9 +2,11 @@
StarlingX Development Process
=============================
This section describes the StarlingX development process.
.. contents::
:local:
:depth: 2
:depth: 1
------------
Introduction

583
doc/source/contributor/doc_contribute_guide.rst
View File

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

50
doc/source/contributor/index.rst
View File

@@ -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`

172
doc/source/contributor/release_note_contribute_guide.rst
View File

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