TITLE | P01: Create documentation for an ONAP |
release (doc project team) |
SUBJECT |
Procedure #01 describes the required tasks |
which are performed by the ONAP 'doc' project |
team and supplying parties to create the release-specific documentation for an ONAP main and maintenance release. |
RELEVANCE
TABLE OF CONTENTS
Although this procedure targets the 'doc' project, it can give general advice for all other ONAP projects to create their release specific documentation. Read "P02: Create documentation for an ONAP release (ONAP project teams)" if you need to create documentation for an ONAP project other than 'doc'. | |||||||
TARGET AUDIENCE | ONAP 'doc' project team: Maintainers of the 'doc' repository Supplying parties: Architecture Subcommittee, ONAP TSC Chair | ||||||
RELEASE RELEVANCE | R12 'London' - R11 'Kohn' | ||||||
TABLE OF CONTENTS |
|
| ||||
AUTHOR |
REVIEWER | - |
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, cherry-pick) related to file changes are also not listed. A development environment to write and preview reStructuredText is highly recommended, also |
some knowledge how to use Inkscape is required. |
01
Update 'doc' project release notes
BRANCH: master
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.
EXAMPLE: 'release-notes.rst' for 'master' branch
02
Update 'marketing' ('composite') release notes
BRANCH: master
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 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.
EXAMPLE: 'index.rst' for 'master' branch
OPEN: Add contacts and describe the process how and when to request the 'marketing' text. Currently responsible for this activity: Eric Debeau
03
Update list of project specific release notes
BRANCH: master
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 reflect 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 TOC - regardless if this project/repository is currently maintained, unmaintaind or in another state. Update the file accordingly for the new release.
EXAMPLE: 'releaserepos.rst' for 'master' branch
The following tasks may have a different relevance depending on the type of release (main, maintenance) you are working on. Optional tasks for a maintenance release marked as 'maintenance (opt)'. They are expected to be performed only if you need to fix issues or you have to incorporate smaller changes. The placeholder '{release}' needs to be substituted by the name of the new release, e.g. 'istanbul' or 'jakarta'.
| |
EXAMPLE CONFIGS | Together with the 'doc' repository the documentation team provides basic 'tox', 'sphinx' and ReadTheDocs example configuration files to be used by other ONAP projects (except 'doc'). Every project containing documentation in ReStructuredText format needs them. The files are:
EXAMPLES ONLY: 'examples' directory in the 'doc' repository (master): FULL: Full file and folder structure of the 'doc' repository (master) to show where active config files are generally stored in a repository.
|
1.0 | MASTER BRANCH PREPARATION |
1.1 | Create a new Jira task and use the ID for all upcoming changesRELEASE: main + maintenance BRANCH: not applicable FILE: n/a DESCR: Generally you need to add an Issue-ID to any gerrit change. Please follow the instructions below.
|
1.2 | Clone 'master' branch of 'doc' repository to your local development environmentRELEASE: main + maintenance BRANCH: 'master' FILE: all DESCR: Please use the command below.
Now you can start to modify files in the 'master' branch. |
2.0 | MASTER BRANCH UPDATES |
2.1 | Ensure correct 'defaultbranch' in '.gitreview'RELEASE: main BRANCH: 'master' FILE: doc/.gitreview DESCR: Check that the 'defaultbranch' entry is pointing to 'master' ('defaultbranch=master'). This can help to avoid that changes are accidentally committed or even published to a wrong branch. EXAMPLE: active '.gitreview' for 'master' branch, 'doc' project
|
2.2 | Update Sphinx configuration file 'conf.py'RELEASE: main + maintenance (opt) BRANCH: 'master |
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).
04
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.
- Open https://gerrit.onap.org/r/admin/repos/doc,branches
- Use [CREATE NEW] function on the top right corner
- Set 'Branch name' to the name of the upcoming release (e.g. 'istanbul')
- Set 'Initial revision' to 'master'
- 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.
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').
05
Clone the new doc branch to your development environment
BRANCH: 'newbranch'
FILE: all
DESCR: Please follow the instructions below.
git clone --branch <newbranch> --recurse-submodules ssh://<username>@gerrit.onap.org:29418/doc
Now you can start to modify files for the new release.
06
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 avoids people from accidently ... ?
EXAMPLE: '.gitreview' for 'honolulu' release/branch
OPEN: Add a description why this is important.
07
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. |
|
|
|
- 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.
08
Update interactive ONAP architecture overview and related files
BRANCH: 'newbranch'
FILE #1: doc/docs/guides/onap-developer/architecture/media/onap-architecture-overview-r<#>-latest-interactive.svg
FILE #2: doc/docs/guides/onap-developer/architecture/onap-architecture.rst
DESCR: Please follow the instructions below.
- Prerequisite: The interactive ONAP architecture overview (svg format, mainly maintained by Thomas Kulik ) has already been aligned to the official ONAP architecture overview for the new release. It must have been updated and prepared to be used in the new branch (e.g. architecture elements in the overview, embedded release info/descriptions/links, labels-and-links file, partly updated file names).
- Rename file 'onap-architecture-overview-r<#>-latest-interactive.svg' to 'onap-architecture-overview-r<#>-<newbranch>-interactive.svg'
- Open file 'onap-architecture-overview-r<#>-<newbranch>-interactive.svg' in Inkscape
- In the 'Objects' window find the 'releaseinfo.link' object / make it visible by clicking on the 'closed eye' symbol and changing it to an 'open eye' symbol / now the release info should be visible on the overview. Save the file.
- Save the file again, but with a new filename. Use 'onap-architecture-overview-r<#>-<newbranch>-interactive-path.svg'. The select all
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
further changes to this 'pathed' version of the overview).
- 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 for the 'pathed' version of the overview ('onap-architecture-overview-r<#>-<newbranch>-interactive-path.svg').
EXAMPLE: 'onap-architecture.rst' for 'master' branch
OPEN: Update example to 'istanbul' branch as soon as possible (pointing to 'master' is misleading here)
Also compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended. EXAMPLE #1: example 'conf.py' for 'master' branch EXAMPLE #2: active 'conf.py' for 'master' branch 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? OPEN: Add note to keep files/content in sync: conf.py / list of project specific release notes / references in 'ONAP Components and Functionalities' section | |
2.3 | Update Sphinx configuration file 'requirements-docs.txt'RELEASE: main BRANCH: 'master' FILE: doc/docs/etc/requirements-docs.txt DESCR: The file contains the required libraries to be used by Sphinx. Compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended. EXAMPLE #1: example 'requirements-docs.txt' for 'master' branch
EXAMPLE #2: active 'requirements-docs.txt' for 'master' branch
|
2.4 | Update Tox configuration file 'tox.ini'RELEASE: main BRANCH: 'master' FILE: doc/tox.ini DESCR: The file is required to customize different tox environments. Compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended.
-chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master EXAMPLE #1: example 'tox.ini' for 'master' branch
EXAMPLE #2: active 'tox.ini' for 'master' branch
OPEN: Update 'upper-constraints' entries here after the final version of the file is available in the 'doc' repo |
2.5 | Update ReadTheDocs build configuration file '.readthedocs.yaml'RELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/.readthedocs.yaml DESCR: The ReadTheDocs build configuration file '.readthedocs.yaml' contains configuration needed to customize ReadTheDocs input and output behavior. Please follow the instructions below.
Also compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended. EXAMPLE #1: example '.readthedocs.yaml', same for 'master' branch and '{release}' EXAMPLE #2: active '.readthedocs.yaml', same for 'master' branch and '{release}' |
2.6 | Update ReadTheDocs configuration file 'ribbon.css'RELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/_static/css/ribbon.css DESCR: The ReadTheDocs configuration file 'ribbon.css' has - among others - an effect on the width of a RTD documentation page. The width has been limited to ensure good readability. Please follow the instructions below.
Also compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended. EXAMPLE #1: example 'ribbon.css', same for 'master' branch and '{release}' EXAMPLE #2: active 'ribbon.css', same for 'master' branch and '{release}' |
2.7 | Update 'doc' project release notes incl. Jira linkRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/release-notes.rst DESCR: The file contains a description of the latest changes in the 'doc' project itself. Update it accordingly for the new release. Also update the Jira link to the '{release}' issues at the bottom of the file. EXAMPLE: 'release-notes.rst' for 'master' branch 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 'istanbul'). Or should we remove - at least - release names in the RTD navigation (column on the left)? |
2.8 | Update composite release notesRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/release/index.rst DESCR: This file contains a brief 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 the 'doc' team together with the ONAP TSC chair. We are using information from the 'Release Key Updates' table which is maintained by the projects during the release process (e.g. 'Release Key Updates' for the 'istanbul' release). The content is provided in text form and has to be converted to reStructuredText format manually. Additional sources of information:
CONTACT: Sandra Jackson Pawel Pawlak EXAMPLE: 'index.rst' for 'master' branch OPEN: Add a task/milestone to the release process? OPEN: Describe the process of conversion to reStructuredText format. Example Source |
2.9 | Update list of project specific release notesRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/release/component-release-notes.rst DESCR: This file contains a table of contents (TOC) for project specific release notes. Important to know: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Update the file accordingly for the new release. EXAMPLE: 'component-release-notes' for 'master' branch OPEN: Add reliable source for 'release participating projects/repositories' and their 'maintenance-state'. OPEN: Describe how to locate and check all the project specific release notes (updated? release number/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 'istanbul'). Or should we remove - at least - release names in the RTD navigation (column on the left)? |
2.10 | Update release historyRELEASE: main + maintenance BRANCH: 'master' FILE: doc/docs/release/history.rst DESCR: This file contains a table with the release history (release number, date, name). Update the file accordingly for the new release. EXAMPLE: 'history.rst' for 'master' branch OPEN: Additional check and update by Architecture Subcommittee required? |
2.11 | Update 'ONAP Overview'RELEASE: main + maintenance (opt) BRANCH: 'master' FILE: docs/platform/overview/index.rst DESCR: This file contains an overview of ONAP authored together with the architecture subcommittee. Update the file accordingly for the new release. CONTACT: Byung-Woo Jun EXAMPLE: 'overview.rst' for 'master' branch OPEN: Activity for the Architecture Subcommittee (change rst file and propose a patch)? Add task/milestone to the release process? To be aligned with marketing department? |
2.12 | Update architecture descriptionRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/platform/architecture/index.rst DESCR: This file contains a description of the ONAP architecture authored together with the architecture subcommittee. Update the file accordingly for the new release. CONTACT:Byung-Woo Jun EXAMPLE: 'docs/platform/architecture/index.rst' for 'master' branch OPEN: Activity for the Architecture Subcommittee (change rst file and propose a patch)? Add task/milestone to the release process? To be aligned with marketing department? |
2.13 | Update interactive ONAP architecture overview diagram and related filesRELEASE: main + maintenance (opt) BRANCH: 'master' FILE #1: doc/docs/platform/architecture/media/onap-architecture-overview-interactive.svg FILE #2: doc/docs/platform/architecture/media/onap-architecture-overview-notes.txt FILE #3: doc/docs/platform/architecture/index.rst FILE #4: doc/docs/platform/architecture/media/onap-architecture-overview-labels-and-links.xlsx CONTACT: Byung-Woo Jun Thomas Kulik DESCR: Please follow the instructions below.
EXAMPLE: 'doc/docs/platform/architecture/index.rst' for 'master' branch OPEN: Describe how to update and test links in xls and svg. |
2.14 | Update references in 'ONAP Components and Functionalities' sectionRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: docs/platform/components/index.rst DESCR: This file contains references to the detailed documentation of ONAP projects, components and functionalities. Important to know: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Update the file accordingly for the new release. EXAMPLE: 'docs/platform/components/index.rst' for 'master' branch |
3.0 | RELEASE BRANCH PREPARATION |
3.1 | Create new branch of the 'doc' repository using gerritRELEASE: main BRANCH: source/initial='master', target/new={release} 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.
OPEN: Currently we are branching the repository early - and consequently have to cherry-pick the changes (done in 'master') for '{release}'. Check if it is ok to branch late (after changing the majority of files). So we can reduce cherry-pick efforts. |
3.2 | Clone '{release}' branch of 'doc' repository to your local development environmentRELEASE: main + maintenance BRANCH: {release} FILE: all DESCR: Please use the command below.
Now you can start to modify files in the new branch. |
4.0 | RELEASE BRANCH UPDATES |
4.1 | Set correct 'defaultbranch' in '.gitreview'RELEASE: main BRANCH: {release} FILE: doc/.gitreview DESCR: Add/update the 'defaultbranch' entry accordingly (e.g. 'defaultbranch=istanbul' for the 'istanbul' branch/release). This can help to avoid that changes are accidentally committed or even published to a wrong branch. EXAMPLE: active '.gitreview' for 'jakarta' branch
|
4.2 | Update Sphinx build configuration file 'conf.py'RELEASE: main + maintenance (opt) BRANCH: {release} 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: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Intersphinx mapping sections for those projects/repositories are removed from 'conf.py'. EXAMPLE: active 'conf.py' for 'jakarta' branch
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? |
4.3 | Update Tox configuration file 'tox.ini'RELEASE: main BRANCH: {release} FILE: doc/tox.ini DESCR: The file is required to customize different tox environments. Compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended.
-chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h={release} EXAMPLE #1: example 'tox.ini' for 'master' branch
EXAMPLE #2: active 'tox.ini' for 'master' branch
|
4.4 | Update interactive ONAP architecture overview diagram and related filesRELEASE: main + maintenance (opt) BRANCH: {release} FILE #1: doc/docs/platform/architecture/media/onap-architecture-overview-interactive.svg FILE #2: doc/docs/platform/architecture/media/onap-architecture-overview-notes.txt FILE #3: doc/docs/platform/architecture/index.rst FILE #4: docs/platform/architecture/media/onap-architecture-overview-labels-and-links.xlsx CONTACT: Thomas Kulik DESCR: Please follow the instructions below.
EXAMPLE: 'onap-architecture.rst' for 'istanbul' branch (TO BE CHANGED! Needs an update to 'index.rst' if 'Kohn' release is available) OPEN: Update example if 'Kohn' release is available ( onap-architecture.rst → doc/docs/platform/architecture/index.rst ) OPEN: 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/{release}'? Do all links work? |
5.0 | READ THE DOCS MAINTENANCE |
5.1 | Deactivate outdated release documentationRELEASE: older than 'current -1' BRANCH: n/a FILE: n/a DESCR: Generally, the latest release of ONAP and the one before is supported. Older releases of documentation can be deactivated in RTD. Remove them from the list of 'Active Versions' which is available for every project (repository). Keep only 'latest', {current release} and {current release -1}. For unmaintained projects only keep 'latest' in the list of 'Active Versions'. You need to be administered as a 'Maintainer' in RTD for every single project you like to (de)activate versions. EXAMPLE: n/a OPEN: To be detailed |
6.0 | IMPROVEMENTS FOR THIS PROCEDURE |
6.1 | Improvements (to be discussed)
|
xx
Template lorem ipsum dolor sit amet
BRANCH: foo
FILE: foo/bar.rst
DESCR: Lorem ipsum dolor sit amet.
EXAMPLE: 'bar.rst' for 'xyz' branch
OPEN: Lorem ipsum dolor sit amet