Deploying the documentation#

This section describes the steps involved in deploying an updated version of the standard to become the live version.

This process is used for major, minor and patch versions, as well as non-normative versions.

For changes to the documentation only (no schema changes), start from merge and release.

Read the Docs configuration#

Read the Docs builds and hosts the standard documentation site.

Whenever a commit is pushed to a branch in the GitHub repository, Read the Docs automatically builds the branch and hosts it at https://open-fibre-data-standard.readthedocs.io/en/<branch name>.

Users can access the documentation for each minor version of the standard via the flyout menu. Other branches are hidden from the menu.

You can find credentials for Read the Docs in the Open Data Services password database.

Prepare for release#

You can skip this section if you are not releasing a new major, minor or patch version.

Perform periodic updates#

Update external codelists#

./manage.py update-codelists

Update the country codelist#

Follow the instructions in the --help message:

python manage.py update-country --help

Update the fibreType codelist#

The codes in the fibreType codelist are identifiers for ITU-T G Series Recommendations that describe the characteristics of optical fibre and cables.

Check the ITU-T G Series Recommendations for recommendations in the range G.651.1-G.659 that do not appear in the fibreType codelist. For each new recommendation:
Add the recommendation number (e.g. G.652) to the fibreType codelist
Set the code’s title to the recommendation number
Set the code’s description to:

```
A <description from ITU-T G Series Recommendations page> that conforms to ITU-T recommendation <recommendation number>.
```

Update version numbers and changelog#

Update the MAJOR.MINOR version number in the following files:

docs/
- conf.py: update version
- *.md */*.md: update release admonition

Update the MAJOR_MINOR_PATCH version number in the following files:

docs/
- conf.py: update release
- reference/schema.md: update canonical network schema URL
- reference/publication_formats/json.md: update canonical network package schema URL
schema/
- network-schema.json: update id
- network-package-schema.json: update id and properties/networks/items/$ref
examples/
- json/*.json: update links/0/href for each network
- geojson/*.geojson: update /properties/network/links/0/href for each feature
- csv/links.csv: update links/0/href

Update the version number and date in the changelog.

Set up a development instance of CoVE#

Set up a development instance of CoVE using the new schema, and run tests against it.

Merge and release#

Merge the development branch onto the live branch#

Create a pull request to merge the development branch into its corresponding live branch, e.g. 0.2-dev into 0.2. This might happen by first merging a patch dev branch (0.2.1-dev) into the minor dev branch (0.2-dev), and then merging into the live branch (0.2). The pull request can be created through GitHub’s web interface.

Create a tagged release#

You can skip this step if you are not releasing a new major, minor or patch version.

Create a tag. For example:

  git tag -a 0__2__0 -m '0.2.0 release'

Push the tag:

  git push --follow-tags

Complete the deployment#

You can skip these steps if you are not releasing a new major, minor or patch version.

Update CoVE#

Update Lib CoVE OFDS#

Update the URL paths in schema.py
Make sure all tests pass
Release a new version

Update and deploy CoVE OFDS#

Upgrade the requirements to use the new version of the CoVE library

  pip-compile -P libcoveofds; pip-compile requirements_dev.in

Update the URL paths in settings.py
Make sure all tests pass
Deploy the app

Update Read the Docs#

In the Read the Docs advanced settings, set Default branch to the branch for the new release.
In the Read the Docs versions settings, edit the branch for the new release and uncheck Hidden.