...
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. 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 | 10.x.x 'Jakarta' – 8.x.x '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, cherry-pick) 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. 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 '{releasename}' needs to be substituted by the name of the new release, e.g. 'istanbul' or 'jakarta'. | ||||||||
1.0 | PREPARATION I | ||||||||
1.1 | Create a new Jira tasks and use the ID for all upcoming changesRELEASE: main + maintenance BRANCH: not applicable FILE: n/a DESCR: 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 | UPDATES IN MASTER BRANCH | ||||||||
2.1 | Update 'doc' project release notesRELEASE: 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. Update it accordingly for the new release. EXAMPLE: 'release-notes.rst' for 'master' branch OPEN: check all 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.2 | Update composite release noteRELEASE: 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. Update the file accordingly - especially the release date. CONTACT: Catherine Lefevre Kenny Paul Eric Debeau OPEN: Add a task/milestone to the release process? OPEN: Describe the process of conversion to reStructuredText format. Example Source | ||||||||
2.3 | Update list of project specific release notesRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/release/releaserepos.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 be a) 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: 'releaserepos.rst' for 'master' branch OPEN: Add reliable source for 'release participating 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). | ||||||||
2.4 | Update release history in overviewRELEASE: main + maintenance BRANCH: 'master' FILE: doc/docs/guides/overview/overview.rst DESCR: This file contains a table with the release history (release number, date, name). Update the file accordingly for the new release. EXAMPLE: 'overview.rst' for 'master' branch OPEN: Additional check and update by Architecture Subcommittee required? | ||||||||
2.5 | Update architecture descriptionRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/guides/onap-developer/architecture/onap-architecture.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: Chaker Al-Hakim Byung-Woo Jun EXAMPLE: 'onap-architecture.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.6 | Update references in 'ONAP Components and Functionalities' sectionRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/guides/onap-developer/developing/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 be a) 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: 'index.rst' for 'master' branch | ||||||||
2.7 | Update sphinx build configuration file 'conf.py'RELEASE: main + maintenance (opt) BRANCH: 'master' 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 be a) 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: '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 relese notes / references in 'ONAP Components and Functionalities' section | ||||||||
2.8 | Update overview descriptionRELEASE: main + maintenance (opt) BRANCH: 'master' FILE: doc/docs/guides/overview/overview.rst DESCR: This file contains an overview of ONAP authored together with the architecture subcommittee. Update the file accordingly for the new release. CONTACT: Chaker Al-Hakim 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.9 | Update interactive ONAP architecture overview diagram and related filesRELEASE: main + maintenance (opt) BRANCH: 'master' 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: Chaker Al-Hakim Byung-Woo Jun Thomas Kulik DESCR: Please follow the instructions below.
EXAMPLE: 'onap-architecture.rst' for 'master' branch OPEN: Describe how to update and test links in xls and svg. | ||||||||
3.0 | PREPARATION II | ||||||||
3.1 | Create new branch of the 'doc' repository using gerritRELEASE: main BRANCH: source/initial='master', target/new='{releasename}' 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 '{releasename}'. Check if it is ok to branch later (after changing the majority of files). So we can reduce cherry-pick efforts. | ||||||||
3.2 | Clone '{releasename}' branch of 'doc' repository to your local development environmentRELEASE: main + maintenance BRANCH: '{releasename}' FILE: all DESCR: Please use the command below.
Now you can start to modify files in the new branch. | ||||||||
4.0 | UPDATES IN RELEASE BRANCH | ||||||||
4.1 | Set correct 'defaultbranch' in '.gitreview'RELEASE: main BRANCH: '{releasename}' 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 accidently committed or even published to a wrong branch. EXAMPLE: '.gitreview' for 'istanbul' release/branch
| ||||||||
4.2 | Update sphinx build configuration file 'conf.py'RELEASE: main + maintenance (opt) BRANCH: '{releasename}' 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: 'conf.py' for 'istanbul' 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. OPEN: Update to 'conf.yaml' required after branching the repo? OPEN: There are plans for upcoming releases to include only projects/repositories which are in 'maintained' state and have created a branch for the new release. | ||||||||
4.3 | Update interactive ONAP architecture overview diagram and related filesRELEASE: main + maintenance (opt) BRANCH: '{releasename}' 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 'istanbul' branch 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/<newbranch>' ? Do all links work? | ||||||||
5.0 | ADDITIONAL OPENTOPICS | ||||||||
5.1 | List ofAdditionalopen topics
|
...