...
TITLE | P01: Create documentation for an ONAP main release (doc project) | ||||||||
SUBJECT | Procedure #01 describes the required tasks which must be performed by the ONAP 'doc' project to create release-specific documentation for an ONAP main release. Although this procedure targets the 'doc' project, it can give general advice for all other ONAP projects to create their release specific documentation. | ||||||||
RELEVANCE | 9.0.0 'Istanbul' – 8.0.0 'Honolulu' | ||||||||
TABLE OF CONTENTS |
| ||||||||
AUTHOR(S) | |||||||||
REVIEWER(S) | use @notation | ||||||||
NOTES | Not every step within a single task is listed. For example, common tasks like 'git' operations (e.g. add, remove, commit, review) are not included. Jira or Gerrit activities (e.g. review, submit) related to file changes are also not listed. A development environment to write and preview reStructuredText is prerequisite, also some knowledge how to use Inkscape is required. | ||||||||
01 | Create a new Jira tasks and use the Issue-ID for the upcoming changesBRANCH: 'newbranch' FILE: n/a DESCR: Please follow the instructions below.
| ||||||||
02 | Create a new branch of the 'doc' project using gerritBRANCH: source/initial=master, target/new='newbranch' FILE: n/a DESCR: Please follow the instructions below.
Note: You are not allowed to delete a branch. If you need to (maybe due to a typo in the process of creation) you have to raise a ticket at the LF IT Support. IMPORTANT: To trigger the documentation build in ReadTheDocs, you must change at least one of the ReStructuredText files (.rst) in this new branch. Only branching your repository does not trigger the RTD doc build process! Only changing config files (e.g. conf.py) does also not trigger the RTD doc build process! | ||||||||
03 | Update 'doc' project release notesBRANCH: master; then cherry-pic for 'newbranch' FILE: doc/docs/release-notes.rst DESCR: The file contains a description of the latest changes in the 'doc' project. Update it accordingly for the new release and cherry-pic the change for 'newbranch'. EXAMPLE: 'release-notes.rst' for 'master' branch OPEN: check all project specific release notes (updated? releasenumber/release name correct? ...) OPEN: Evaluate if we can/should have only 'placeholder' files in the 'master' branch. This may avoid confusion in case people are looking to 'master' and seeing release specific content (e.g. related to 'honolulu'). Or should we remove - at least - release names in the RTD navigation (column on the left)? | ||||||||
04 | Update 'marketing' ('composite') release noteBRANCH: master; then cherry-pic for 'newbranch' FILE: doc/docs/release/index.rst DESCR: This file contains a ('marketing') overview about the advantages and latest developments related to the new release. It is also known as the 'composite' release note. The text is authored by LFN marketing and the ONAP TSC chair. It is provided in text form and has to be converted to reStructuredText format manually. Update the file accordingly - especially the release date and cherry-pic the change for 'newbranch'. CONTACT: Catherine Lefevre Kenny Paul Eric Debeau Brandon Wick EXAMPLE: 'index.rst' for 'master' branch OPEN: Describe how and when to request the 'marketing' text. Describe the process of conversion to reStructuredText format. Example Source | ||||||||
05 | Update list of project specific release notesBRANCH: master; then cherry-pic for 'newbranch' FILE: doc/docs/release/releaserepos.rst DESCR: This file contains a table of contents (TOC) for project specific release notes. There are several sections to represent the current maintenance state of every project. Whenever a project/repository is deployed via OOM (standard ONAP installation), its release note must be part of the list - regardless if this project/repository is currently maintained, unmaintained or in another state. Update the file accordingly for the new release and cherry-pic the change for 'newbranch'. EXAMPLE: 'releaserepos.rst' for 'master' branch OPEN: Add reliable source for 'release partizipating projects/repositories' and their 'maintenance-state' and - in addition - those ('unmaintained') projects which are deployed 'on top' by OOM team (because the projects/repos are still required for a good reason). | ||||||||
NEW | update release information in https://docs.onap.org/en/latest/guides/overview/overview.html#onap-release-information | ||||||||
06 | Clone the new doc branch to your local development environmentBRANCH: 'newbranch' FILE: all DESCR: Please use the command below.
Now you can start to modify files in the new branch. | ||||||||
07 | Set correct 'defaultbranch' in '.gitreview'BRANCH: 'newbranch' FILE: doc/.gitreview DESCR: Add/update the 'defaultbranch' entry accordingly (e.g. 'defaultbranch=honolulu' for the 'honolulu' branch/release). This can help to avoid that changes are accidently committed or even published to a wrong branch. EXAMPLE: '.gitreview' for 'istanbul' release/branch
| ||||||||
08 | Update sphinx build configuration fileBRANCH: 'newbranch' FILE: doc/docs/conf.py DESCR: The Sphinx build configuration file 'conf.py' contains configuration needed to customize Sphinx input and output behavior. Please follow the instructions below.
Note: The different 'intersphinx_mapping' sections in the 'conf.py' represent the different state of development in the ONAP projects and their repositories. We have to differentiate between:
EXAMPLE #1: 'conf.py' for 'master' branch EXAMPLE #2: 'conf.py' for 'honolulu' branch/release
OPEN: update example #2 to istanbul OPEN: Add reliable source for the info if a project has/hasn't branched. OPEN: Include changes/actions required because we have introduced constraints-files. OPEN: Update to 'conf.yaml' required after branching the repo? | ||||||||
new | Update sphinx configuration file 'tox.ini'BRANCH: 'newbranch' FILE: doc/tox.ini DESCR: Lorem ipsum dolor sit amet. CONTACT: optional; use @notation EXAMPLE: 'bar.rst' for 'xyz' branch OPEN: optional | ||||||||
09 | Update interactive ONAP architecture overview and related filesBRANCH: 'newbranch' FILE #1: doc/docs/guides/onap-developer/architecture/media/onap-architecture-overview-interactive.svg FILE #2: doc/docs/guides/onap-developer/architecture/onap-architecture.rst CONTACT: Thomas Kulik DESCR: Please follow the instructions below.
EXAMPLE: 'onap-architecture.rst' for 'master' branch OPEN: Update example to 'istanbul' branch as soon as possible (pointing to 'master' is misleading here); describe how to update and test links in xls and svg. OPEN: Update links in 'onap-architecture-overview-interactive.svg' by using an editor and replacing very carefully '/en/latest/' with '/en/<newbranch>' ? Do all links work? | ||||||||
Additional open topics
| |||||||||
00 | TemplateBRANCH: foo FILE: foo/bar.rst DESCR: Lorem ipsum dolor sit amet. CONTACT: optional; use @notation EXAMPLE: 'bar.rst' for 'xyz' branch OPEN: optional |
...