As discussed in Yoga PTG[1] and centos stream 9 is released, we are updating Yoga testing runtime with: - Add Debian 11 as tested distro - Change centos stream 8 -> centos stream 9 - Bump lowest python version to test to 3.8 and highest to python 3.9 [1] https://etherpad.opendev.org/p/tc-yoga-ptg Change-Id: I2fb3a1daa5ee812ea45bab0c2fb7c0997dc2d116
4.8 KiB
Project Testing Interface
OpenStack has a lot of projects. For each project, the OpenStack CI system needs to be able to perform a lot of tasks. If each project has a slightly different way to accomplish those tasks, it makes the management of a consistent testing infrastructure very difficult to deal with. Additionally, because of the high volume of development changes and testing, the testing infrastructure has to be able to pre-cache artifacts that are normally fetched over the internet. To that end, each project should support a consistent interface for driving tests and other necessary tasks.
The following tasks are required for every project. Every project must:
- Execute tests
- Enforce code style
- Generate a code coverage report
- Generate a source tarball
- Generate documentation
- Generate releasenotes
The following are other common tasks, which may not be relevant for every project:
- Enforce code coverage
- Generate a release artifact
- Publish a release artifact
- Import translation strings
- Export translation strings
Tools and approaches vary by language, please choose which language is relevant to you.
Documentation
OpenStack has decided to standardize on using Sphinx for project documentation, regardless of programming language.
Note
The use of sphinx for documentation is intended for documentation that is not written inside of docstrings or code comments. Languages, such as Go, that natively support a system for documenting the code through code comments, should use those native systems. Sphinx is intended to be used for documentation that is not written inline with the code.
To support documentation generation, projects should:
- Have sphinx documentation source in
doc/source
- List python dependencies needed for documentation in
doc/requirements.txt
- List distro package pre-reqs for dependencies in
bindep.txt
using thedoc
tag. - Depend on
openstackdocstheme
for documentation and configure it to be used indoc/source/conf.py
. - Have a
docs
environment set up in atox.ini
file within the repository.
Assuming non-Python requirements have been properly installed as
indicated by bindep.txt
, the following command should work
with no additional setup and should result in the documentation being
emitted into doc/build/html
.
tox -e docs
Note
We strongly discourage project teams from adding commands to the
docs
environment beyond:
sphinx-build -W -b html doc/source doc/build/html
Additional logic needed around Sphinx generation should go into Sphinx plugins.
Language specific instructions supplement these and are in addition to them.
Release Notes
OpenStack uses reno for generating release notes regardless of programming language.
To support releasenotes generation, projects should:
- Have releasenotes documentation source in
releasenotes/
- Configure
openstackdocstheme
to be used inreleasenotes/source/conf.py
. - Optionally list distro package pre-reqs for dependencies in
bindep.txt
using thereleasenotes
tag.
Assuming requirements have been properly installed, the following
command should work with no additional setup and should result in the
releasenotes being emitted into
releasenotes/build/html
.
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \
releasenotes/source releasenotes/build/html
Language specific instructions supplement these and are in addition to them.
Linux Distributions
The following free operating systems are representative of platforms regularly used to deploy OpenStack on:
Below are the two upstream testing required as minimum to consider the above distro for defining the testing runtime:
- devstack support with distro job as voting
- One of the deployment projects run OpenStack on distro
pti/*
Tested Runtimes
In order to focus development efforts and prevent breaking changes
midway through a development cycle, the policy for officially tested
runtimes is based on the LTS or stable release of the pti-linux-distros
at the
start of the development cycle. Distros are listed in testing runtime
based on the required minimum testing as described in pti-linux-distros
The officially tested runtimes for each cycle can be found here:
runtimes/*