ed5bddca67
1. Updated index page to include toctree for proposed organization of docs. Updated sample content (this needs to be finalized - SAMPLE content only). 2. Added Installation Guide page. Migrated content from wiki to docs (reST). 3. Added Developer Guide page. Migrated content from wiki to docs (reST). 4. Updated Contribute page to link to 2 child pages - Added API Contributor Guide page. Migrated content from wiki to docs (reST). - Added Release Notes Contributor Guide page. Added draft content from etherpad (reST). 5. Removed trailing white space in files (patch) Depends-On: https://review.openstack.org/#/c/611078 Change-Id: If4448fcc096f8fdcdf0d88c31b6b42ea94aea1fd Signed-off-by: Kristal Dale <kristal.dale@intel.com>
138 lines
4.7 KiB
ReStructuredText
138 lines
4.7 KiB
ReStructuredText
===============================
|
|
Release Notes Contributor Guide
|
|
===============================
|
|
|
|
**[DRAFT]**
|
|
|
|
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,
|
|
generate HTML files. More details about the Reno Release Notes Manager can
|
|
be found at: https://docs.openstack.org/reno
|
|
|
|
---------
|
|
Locations
|
|
---------
|
|
|
|
StarlingX Release Notes documentation exists in the following projects:
|
|
|
|
- **stx-clients:** StarlingX Client Libraries
|
|
- **stx-config:** StarlingX System Configuration Management
|
|
- **stx-distcloud:** StarlingX Distributed Cloud
|
|
- **stx-distcloud-client:** StarlingX Distributed Cloud Client
|
|
- **stx-fault:** StarlingX Fault Management
|
|
- **stx-gui:** StarlingX Horizon plugins for new StarlingX services
|
|
- **stx-ha:** StarlingX High Availability/Process Monitoring/Service Management
|
|
- **stx-integ:** StarlingX Integration and Packaging
|
|
- **stx-metal:** StarlingX Bare Metal and Node Management, Hardware Maintenance
|
|
- **stx-nfv:** StarlingX NFVI Orchestration
|
|
- **stx-tools:** StarlingX Build Tools
|
|
- **stx-update:** StarlingX Installation/Update/Patching/Backup/Restore
|
|
- **stx-upstream:** StarlingX Upstream Packaging
|
|
|
|
--------------------
|
|
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:
|
|
|
|
::
|
|
|
|
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:
|
|
|
|
- **.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
|
|
|
|
See stx-config [Doc] Release Notes Management as an example of this first commit:
|
|
https://review.openstack.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 StarlingX System
|
|
Configuration Management:
|
|
`Release Summary r/2018.10 <http://git.openstack.org/cgit/openstack/stx-config/tree/releasenotes/notes/release-summary-6738ff2f310f9b57.yaml>`_
|
|
|
|
::
|
|
|
|
stx-config/releasenotes/
|
|
├── notes
|
|
│ └── release-summary-6738ff2f310f9b57.yaml
|
|
|
|
|
|
To create a new release note that document your code changes via tox newnote environment:
|
|
|
|
$ tox -e newnote hello-my-change
|
|
|
|
A YAML source file is created with a unique name under releasenote/notes/ directory:
|
|
|
|
::
|
|
|
|
stx-config/releasenotes/
|
|
├── notes
|
|
│ ├── hello-my-change-dcef4b934a670160.yaml
|
|
|
|
The content are gound 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 <http://www.sphinx-doc.org/en/stable/rest.html>`_ format.
|
|
|
|
------------------
|
|
Developer Workflow
|
|
------------------
|
|
|
|
#. 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 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 git tag.
|
|
#. Generate the Reno Report
|
|
#. Add your change and submit for review
|