Versions Compared

Old Version 120

changes.mady.by.user Thomas Kulik

Saved on

compared with

New Version 121

changes.mady.by.user Thomas Kulik

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

TITLE

P01: Create documentation for an ONAP main release

SUBJECT
Procedure #01 describes the required tasks which must be performed by the ONAP 'doc' project and supplying parties to create release-specific documentation for an ONAP main release.
RELEVANCE
9.0.0 'Istanbul' – 8.0.0 'Honolulu'
TABLE OF CONTENTS

Table of Contents
maxLevel3
minLevel3
styledisk

AUTHOR(S)

Thomas Kulik

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

used as

and use the Issue-ID for the upcoming changes

BRANCH: 'newbranch'

FILE: n/a

DESCR: Please follow the instructions below.

  1. Open https://https://jira.onap.org/
  2. Create a new task for the 'doc' project and assign name it e.g. "Create docs for '<newbranch>' release". Assign it to the new release 'newbranch'. It should be use as the 'Issue-ID:' required for submitting all related changes to gerrit.
02

Create a new branch of the 'doc' project in gerrit

BRANCH: source/initial=master, target/new='newbranch'

FILE: n/a

DESCR: Please follow the instructions below.

  1. Open https://gerrit.onap.org/r/admin/repos/doc,branches
  2. Use [CREATE NEW] function on the top right corner
  3. Set 'Branch name' to the name of the upcoming release (e.g. 'istanbul')
  4. Set 'Initial revision' to 'master'
  5. Use [CREATE] to create the new branch

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.

03

Update 'doc' project release notes

BRANCH: 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

› View in RTD

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 note

BRANCH: 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

› View in RTD

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 notes

BRANCH: 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

› View in RTD

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

06

Clone the new doc branch to your local development environment

BRANCH: 'newbranch'

FILE: all

DESCR: Please use the command below.

git clone --branch <newbranch> --recurse-submodules ssh://<username>@gerrit.onap.org:29418/doc

Now you can start to modify files in the new branch.

07

Set correct 'defaultbranch' for '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 submitted or even published to a wrong branch.

EXAMPLE: '.gitreview' for 'honolulu' release/branch

 

08

Update Sphinx build configuration file

BRANCH: '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.

  1. On top of the file, set "branch = 'newbranch'".
  2. Set 'intersphinx_mapping' for all participating projects/repositories.
  3. Update 'linkcheck_ignore' entries if required.

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:

  • Projects/repos that have created a branch for the upcoming release. That's why the entries are mapping to project documentation in the new created branch (branch = 'newbranch').
  • Projects/repos that have not created a branch for the upcoming release, but for a previous release. That's why the entries are mapping to project documentation in a previous branch (e.g. branch = 'frankfurt' or branch = 'guillin').
  • Projects/repos that have never created a branch. That's why the entries are mapping to project documentation in the 'master' branch of ONAP (branch = 'latest'). The ONAP 'master' branch is mapped to 'latest' in ReadTheDocs.

EXAMPLE #1: 'conf.py' for 'master' branch

EXAMPLE #2: 'conf.py' for 'honolulu' branch/release

 

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.

09

Update interactive ONAP architecture overview and related files

BRANCH: '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.

  1. PREREQUISITE: The interactive ONAP architecture overview (svg format, maintained by the 'doc' project team) must already have been aligned to the official ONAP architecture overview (maintained by the Architecture Subcommittee) for the new release. It must have been updated and prepared to be used in the new branch (architecture elements in the interactive overview). The embedded release info/descriptions/links and labels-and-links.xlsx file must be updated to reflect the new release.
  2. Open the file 'onap-architecture-overview-labels-and-links.xlsx', change links to point to 'newbranch' and not 'latest'; check if links are reachable (to be detailed)
  3. Open file 'onap-architecture-overview-interactive.svg' in Inkscape
  4. In the 'Objects' window find the 'releaseinfo.link' object. Make it visible by clicking on the 'closed eye' symbol to change it to an 'open eye' symbol. Now the release info should be visible on the overview.
  5. Click on tab 'Object attributes' and check/update the content of the field 'Href:' (the link must point to 'newbranch', not 'latest').
  6. Check/update also the content of the field 'Title:' to the new release number and name (e.g. 'ONAP Release 9 »Istanbul«').
  7. Check and update all embedded links to point to 'newbranch' and not 'latest'. (to be detailed; search and replace in editor?)
  8. Save the file.
  9. Save the file a second time, but with a new filename. Use 'onap-architecture-overview-interactive-path.svg'.
  10. Then select all (warning) elements in the map and use the Inkscape function 'Path → Object to Path' to convert all elements to pathes. Read more about this in the onap-architecture-overview-notes.txt . Save the overview map, close Inkscape (and remember to do no (warning) further changes to this 'pathed' version of the overview).
  11. Edit 'doc/docs/guides/onap-developer/architecture/onap-architecture.rst' and update the '.. raw:: html' section which contains the filename of the interactive ONAP architecture overview. You must use the filename of the 'pathed' version ('onap-architecture-overview-interactive-path.svg').

EXAMPLE: 'onap-architecture.rst' for 'master' branch

› View in RTD

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

  • Include task for a review process for all documents authored by 'doc' to ensure that their content has relevance also for the new ONAP release?
  • Configuration of the RTD 'default version' ('newbranch' as the starting point, not 'latest')
  • Review process for procedures (incl. field for reviewer name and review date) required?
  • Availability and consideration of 'Release Key Update' information (see example for 'Honolulu' release) 
  • Tagging of the 'doc' branch (e.g. '8.0.0' for a main release or '8.0.1' for its first maintenance update)? Still required?
  • Describe the relation to the ONAP release lifecycle process (milestones)? And include the management of Jira tickets related to the described activities here in this procedure?
  • Stick embedded git file examples to a dedicated commit id to avoid that files are changed and then do not match anymore to the description in the task?
  • ReCheck/ReVerify in gerrit for projects which have created their 'newbranch' but where docs are not yet available in RTD?
00

Template lorem ipsum dolor sit amet

BRANCH: foo

FILE: foo/bar.rst

DESCR: Lorem ipsum dolor sit amet.

CONTACT: optional; use @notation

EXAMPLE: 'bar.rst' for 'xyz' branch

› View in RTD

OPEN: optional

...