You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 58 Next »


TITLE

P01: Create documentation for an ONAP main release

SUBJECT
This procedure describes the required tasks for the ONAP doc project itself and supplying ONAP projects to create release-specific documentation for an ONAP main release.
TABLE OF CONTENTS

AUTHOR(S)

Thomas Kulik

TASKS
Note: Not every step within a single task is listed here. For example, a detailed description of a 'git commit' and the following 'git review' process is not explained.

Update 'doc/docs/release-notes.rst' in the 'master' branch

This file contains a description of the latest changes in the 'doc' project. Update it accordingly for the new release.

Example: 'release-notes.rst' in the 'master' release/branch


Update 'doc/docs/release/index.rst' in the 'master' branch

This file contains an (marketing) overview about the advantages and latest developments in the new release. It is also known as the 'composite release note'. The text is authored by LFN marketing and the ONAP TSC chair. Update the file accordingly - especially the release date.

Example: 'index.rst' (composite release note) in the 'master' release/branch

OPEN: Add contacts and describe the process how and when to request the 'marketing' text. Currently responsible for this activity: Eric Debeau


Update 'doc/docs/release/releaserepos.rst' in the 'master' branch

This file contains a table of contents (TOC) for project specific release notes. There are several sections to reflect the current maintenance state of every project. In case, a project/repository is deployed via OOM (standard ONAP installation), its release note is part of the TOC - regardless if this project/repository is currently maintained, unmaintaind or in another state. Update it accordingly for the new release.

Example: 'releaserepos.rst' in the 'master' release/branch

OPEN: Add reliable source for 'release partizipating projects/repositories', their 'maintenance-state' and - in addition - those ('unmaintained') projects which are deployed in addition by OOM team.


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

  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

OPEN: Evaluate if we can/should update all files AFTER we have created the branch (and having 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').


Clone the new doc branch to your development environment

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


Update 'doc/docs/conf.py' in the new branch

  1. Set "branch = 'newbranch'" on top of the file
  2. Set 'intersphinx_mapping' for all participating projects and their repositories
  3. Update 'linkcheck_ignore' entries if required

Note: The different 'intersphinx_mapping' sections in the 'conf.py' reflect the different state of development in the projects and their repositories. We have to differentiate between:

  • Projects 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 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 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 called 'latest' in ReadTheDocs.

Example #1: 'conf.py' for the 'master' release/branch

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

 

OPEN: Add reliable source for the info if/if not a project has branched.


Update 'doc/.gitreview' in the new branch

Add/update the 'defaultbranch' (e.g. 'defaultbranch=honolulu')

Example: '.gitreview' for the 'honolulu' release/branch

 

OPEN: Add a description why this is important


Template

  1. Lorem ipsum dolor sit amet

OPEN: Template

  • No labels