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.

To add a community translation, follow Add a community translation.

Create new versions of extensions¶

Note

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

The conf.py file refers to specific versions of some extensions. The governance process will establish whether to create new versions of these extensions.

Check for open pull requests and for missing changelog entries. You can run this Rake task to get links to pull requests and comparison URLs:

bundle exec rake release:review_extensions ORG=open-contracting-extensions

For each extension for which to create a new version:

From the list of releases, click Draft a new release
In Tag version, enter the version number in vmajor.minor.patch format, e.g. v1.1.1
Enter a summary of changes as the release message, and click Publish release

Alternately, run this Rake task, which will use the extension’s changelog as the release message:

bundle exec rake release:release_extensions REF=v1.1.1 REPOS=repo1,repo2

If you make a mistake, you can undo the release with:

bundle exec rake release:undo_release_extensions REF=v1.1.1 REPOS=repo1,repo2

Then, add the new releases to the extension registry. Change to the local directory of the extension_registry repository, and run:

./manage.py refresh

Prepare for release¶

Note

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

1. Perform maintenance tasks¶

See Maintenance.

2. Perform periodic updates¶

Before each release, and at least once a year:

Update external codelists:
```
python manage.py update
```
Update the country codelist, following the instructions in the --help message:
```
python manage.py update-country --help
```
Check ISO 6523 for new organization identifier schemes:
```
python manage.py check-iso-6523
```
If any codes are output:
- Add the codes to the ISO6523-analysis spreadsheet.
- Update the GitHub issue to note that the new codes need to be assessed for inclusion in org-id.guide, and that the script needs to be updated to recognize the new codes.

3. Update version numbers and changelog¶

In docs/conf.py, update release to e.g. 1.1.1 and update version if appropriate.

Update the major__minor__patch version number:

find . \( -name '*.json' -or -name '*.md' -or -name '*.po' \) -exec sed -i "" 's/1__1__3/1__1__4/g' '{}' \;

4. Set up a development instance of CoVE (OCDS Data Review Tool)¶

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

Merge and release¶

1. Push and pull updated translations¶

Push strings to translate to Transifex.
Check all strings are translated and reviewed in supported translations.
For any resources with untranslated or unreviewed strings, follow the Translation workflow.
View translations with warnings on Transifex, and correct translated text if necessary.
Pull supported translations from Transifex.
View translations with issues on Transifex, and correct source and .po files if necessary.
If .po files were corrected, you may need to Push translations to Transifex.
Create a pull request for the updated translation files.
Test the translations on the build of the pull request.

2. Merge the development branch onto the live branch¶

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

3. Create a tagged release¶

Note

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 1__1__0 -m '1.1.0 release.'
```
Push the tag:
```
git push --follow-tags
```

Warning

Only tag a commit on a live branch like 1.1. Otherwise, the deployment scripts might release older versions of the files.

Complete the deployment¶

After merging branches, GitHub Actions automatically:

Deploys the build of any live branch (e.g. 1.1) to the live directory (/home/ocds-docs/web), as a build directory named {branch}-{timestamp} (e.g. 1.1-1577836800)
Creates a symlink named after the live branch (e.g. 1.1) that points to the build directory. As such, you can rollback changes by linking to another build directory.
Deploys the schema files, codelist files and metadata file (if any), if a tag is pushed: for example, under https://standard.open-contracting.org/schema/, https://standard.open-contracting.org/profiles/ppp/schema/ and https://standard.open-contracting.org/profiles/ppp/extension/.

The live branches are configured in the last step of the repository’s ci.yml workflow.

1. Update the deploy repository¶

Note

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

See the deploy repository’s documentation.

2. Update the Data Review Tool¶

Note

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

Update the CoVE library¶

This is the lib-cove-ocds repository for OCDS, and lib-cove-oc4ids for OC4IDS.

Update the URL paths in config.py
OC4IDS: Add new organization references to ORG_PATHS regular expression
Make sure all tests pass
Release a new version

Update and deploy the Data Review Tool¶

This is the cove-ocds repository for OCDS, and cove-oc4ids for OC4IDS.

Upgrade the requirements to use the new version of the CoVE library (libcoveocds or libcoveoc4ids).
Update the URL paths in settings.py (only in cove-ocds)
Make sure all tests pass
Deploy the app

Update any other tools that use the CoVE library¶

Make sure other tools that use libcoveocds (like Kingfisher Process) are updated to use the new version.

Many tools will use the default options from the library, and these tools will start using the new version of the schema straight away. But if the tool overrides those options with its own options, the tool’s own options may need changing.