OCDS documentation¶

Add a new language¶

In salt/apache/files/sites/docs.conf.include, add the new language in the options variable.
In tests/test_docs.py, update the languages variable.

Add a new minor version¶

Below, substitute {root}, {current-minor-branch} and {old-minor-branch}. For example: ppp, 1.1 and 1.0.

Edit salt/apache/files/docs/robots.txt

If the profile has a version, add:

Disallow: /profiles/{root}/{current-minor-branch}

If the profile has older minor versions, also add, for each old minor version:
```
Disallow: /profiles/{root}/{old-minor-branch}
```

Publish draft documentation¶

To configure a documentation repository to push builds to the server:

Access the repository’s Settings tab
Click Secret and variables
Click Actions
Set the private key:
1. Click New repository secret
2. Set Name to “PRIVATE_KEY”
3. Set Value to the contents of salt/private/keys/docs_ci
4. Click Add secret
Set the Elasticsearch password:
1. Click New repository secret
2. Set Name to “ELASTICSEARCH_PASSWORD”
3. Set Value to the password of the manage user in the pillar/private/docs.sls file
4. Click Add secret

Publish released documentation¶

Follow the OCDS Development Handbook’s deployment guide.

1. Update this repository¶

Note

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

Below, substitute {root}, {latest-branch}, {dev-branch}, {formatted-dev-branch}, {version} and {name}. For example: ppp, latest, 1.0-dev, 1.0 Dev, 1.0.0.beta and OCDS for PPPs.

If this is the first numbered version of a profile:

Update salt/docs/robots.txt.
In salt/apache/files/sites/docs.conf.include, add the profile’s latest branch, minor series and languages in the options variable.
In tests/test_docs.py, update the versions, languages and banner_live variables.

Add a salt/docs/includes/version-options-profiles-{root}.html file to this repository:

<option>Version</option>
<option value="{latest-branch}">{version} ({latest-branch})</option>

Add a salt/docs/includes/banner_staging_profiles_{root}.html file to this repository:

<div class="oc-fixed-alert-header">
    This is a development copy of the {name} docs, the <a href="/profiles/{root}/{latest-branch}/en/">latest live version is here</a>.
</div>

Otherwise:

In the appropriate salt/docs/includes/version-options*.html file, update the version number in the text of the first option element.

If this is a new major or minor version:

In salt/docs/robots.txt, disallow the minor branch and its dev branch, for example:
```
Disallow: /1.2
Disallow: /1.2-dev
```
In salt/apache/files/sites/docs.conf.include, add the minor series in the options variable, and add a new Location directive like:
```
<Location /1.1/>
    SetEnv BANNER /includes/banner_old.html
</Location>
```
In ocdsindex-exclude.txt, add the base URL of the new version.
In tests/test_docs.py, update the versions, banner_live and banner_old variables.
In the appropriate salt/docs/includes/banner_staging*.html file and salt/docs/includes/banner_old*.html> file (if any), update the minor series.
In the appropriate salt/docs/includes/version-options*.html file, add an option element to the “Live” optgroup for the previous minor series and previous version number, for example:
```
<option value="0.9">0.9.2</option>
```

2. Update other repositories¶

Update the Data Review Tool and any other tools per this spreadsheet.

Migrate from an old server¶

Copy the /home/ocds-docs/web directory. For example:

rsync -avz ocp99:/home/ocds-docs/web/ /home/ocds-docs/web/

Stop Elasticsearch, replace the /var/lib/elasticsearch/ directory, and start Elasticsearch. For example:

systemctl stop elasticsearch
rm -rf /var/lib/elasticsearch/*
rsync -avz ocp99:/var/lib/elasticsearch/ /var/lib/elasticsearch/
systemctl start elasticsearch

Mark the elasticsearch package as held back:
```
apt-mark hold elasticsearch
```