...
TITLE | P01: Create documentation for an ONAP main release | ||||||||
SUBJECT | This procedure describes the required tasks for the ONAP doc project itself and supplying parties to create release-specific documentation for an ONAP main release. | ||||||||
TABLE OF CONTENTS |
| ||||||||
AUTHOR(S) | |||||||||
TASKS | NoteNOTE: 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. A develoment environment to write and preview reStructuredText is prerequisite. | 01||||||||
00 | Update 'doc' project release notesBRANCH: master FILE: doc/docs/release-notes.rst ' in the 'master' branchDESCR: The This file contains a description of the latest changes in the 'doc' project. Update it accordingly for the new release. ExampleEXAMPLE: 'release-notes.rst' in the'master' release/branch | ||||||||
00 | Update 'marketing' ('composite') release notesBRANCH: master FILE: doc/docs/release/index.rst ' in the 'master' branchDESCR: 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'notes. 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. ExampleEXAMPLE: '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 ' | ||||||||
00 | Update list of project specific release notesBRANCH: master FILE: doc/docs/release/releaserepos.rst ' in the 'master' branchDESCR: 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, Whenever a project/repository is deployed via OOM (standard ONAP installation), its release note is must be part of the TOC - regardless if this project/repository is currently maintained, unmaintaind or in another state. Update it the file accordingly for the new release. ExampleEXAMPLE: 'releaserepos.rst' in the'master' release/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). | ||||||||
00 | Create a new branch of the 'doc' project in gerritBRANCH: source/initial=master, target/new='newbranch' FILE: n/a DESCR: Please follow the instructions below.
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'). | ||||||||
00 | Clone the new doc branch to your development environmentBRANCH: 'newbranch' FILE: n/a DESCR: Please follow the instructions below. git clone --branch <newbranch> --recurse-submodules ssh://<username>@gerrit.onap.org:29418/doc | ||||||||
00 | Update Sphinx build configuration fileBRANCH: 'newbranch' FILE: doc/docs/conf.py DESCR: The Sphinx build configuration file 'conf.py' contains all configuration needed to customize Sphinx input and output behavior. Please follow the instructions below.
Note: The different 'intersphinx_mapping' sections in the 'conf.py' reflect the different state of development in the ONAP projects and their repositories. We have to differentiate between:
EXAMPLE #1: 'conf.py' for the 'master' branch EXAMPLE #2: 'conf.py' for the 'honolulu' branch/release
OPEN: Add reliable source for the info if/if not a project has branched. | ||||||||
00 | Update 'doc/docs/conf.py' in the new branch
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:
Example #1: 'conf.py' for the 'master' release/branchExample #2: 'conf.py' for the 'honolulu' release/branch
OPEN: Add reliable source for the info if/if not a project has branched. | ||||||||
00 | Update 'doc/.gitreview' in the new branchAdd/update the 'defaultbranch' (e.g. 'defaultbranch=honolulu') Example: '.gitreview' for the 'honolulu' release/branch
OPEN: Add a description why this is important | ||||||||
00 | Template lorem ipsum dolor sit ametBRANCH: foo FILE: foo/bar.rst DESCR: Lorem ipsum dolor sit amet. EXAMPLE: 'bar.rst' in 'master' branch OPEN: Lorem ipsum dolor sit amet |