# 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](#merge-and-release).

## Read the Docs configuration

[Read the Docs](https://readthedocs.org/) builds and hosts the standard documentation site.

Whenever a commit is pushed to a branch in the [GitHub repository](repository.md), 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](https://docs.readthedocs.io/en/stable/flyout-menu.html). 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

```bash
./manage.py update-codelists
```

#### Update the country codelist

Follow the instructions in the `--help` message:

```bash
python manage.py update-country --help
```

#### Update the fibreType codelist

The codes in the [fibreType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#fibretype) are identifiers for [ITU-T G Series Recommendations](https://www.itu.int/rec/T-REC-G/en) that describe the characteristics of optical fibre and cables.

1. 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:
  1. Add the recommendation number (e.g. G.652) to the fibreType codelist
  1. Set the code's title to the recommendation number
  2. 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.

1. Create a tag. For example:

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

2. Push the tag:

```bash
  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](https://github.com/Open-Telecoms-Data/lib-cove-ofds/blob/main/libcoveofds/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

```bash
  pip-compile -P libcoveofds; pip-compile requirements_dev.in
```
- Update the URL paths in [settings.py](https://github.com/Open-Telecoms-Data/cove-ofds/blob/live/cove_project/settings.py)
- Make sure all tests pass
- Deploy the app

### Update Read the Docs

- In the Read the Docs [advanced settings](https://readthedocs.org/dashboard/open-fibre-data-standard/advanced/), set `Default branch` to the branch for the new release.
- In the Read the Docs [versions settings](https://readthedocs.org/projects/open-fibre-data-standard/versions/), edit the branch for the new release and uncheck `Hidden`.