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 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
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
The directory structure of release documentation under each StarlingX project
repository is fixed. This example shows the
releasenotes/ ├── notes │ └── release-summary-6738ff2f310f9b57.yaml └── source ├── conf.py ├── index.rst └── unreleased.rst
The initial modifications and additions to enable the API Documentation service in each StarlingX project are as follows:
Modifications to ignore the building directories and HTML files for the release notes.
Modifications to add jobs to build and publish the
Directory created to store your release notes files in YAML format.
Directory created to store your API reference project directory.
Configuration file to determine the HTML theme, Sphinx extensions, and project information.
Source file to create your index RST source file.
Source file to avoid breaking the real release notes build job on the master branch.
Modifications to add the
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/
Once the Release Notes Documentation service has been enabled, you can create a new release notes.
Release notes files¶
The following shows the YAML source file for the stx-config project:
stx-config/releasenotes/ ├── notes │ └── release-summary-6738ff2f310f9b57.yaml
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
stx-config/releasenotes/ ├── notes │ ├── hello-my-change-dcef4b934a670160.yaml
The content is grouped into logical sections based in the default template used by reno:
features issues upgrade deprecations critical security fixes other
Modify the content in the YAML source file based on reStructuredText format.
Start common development workflow to create your change: “Hello My Change”.
Create its release notes, no major effort since title and content might be reused from the Git commit information.
Add your change including its release notes and submit for review.
Release team workflow¶
Start development work to prepare the release. This might include a Git tag.
Generate the Reno Report.
Add your change and submit for review.