Publishing a new version

This document contains the step-by-step instruction for publishing a new documentation version.

1. Create the new documentation release branch

After releasing a new version of the software we expect to release the corresponding documentation. Similarly to the code branches we'll need to create a new branch for the new software release named docs-release-[major].[minor] where the [major] and [minor] correspond to the software just released.

First, checkout the documentation development branch:

git checkout docs-develop

Then create the new release branch:

git checkout -b docs-release-[major].[minor]

git push --set-upstream origin docs-release-[major].[minor]

This will kick-off the Github automation that will build and deploy the documentation on the gh-pages branch.

You should be now able to select the new version from the dropdown menu at the top of the published page.

2. Update the default version to serve

For setting this release as the one to be served by default you'll simply need to (after pull-ing the latest changes) run the following mike command:

mike alias docs-release-[major].[minor] latest --update-aliases --push

Troubleshooting

No write permissions on repository

If you don’t have write permissions and need to open a PR for updating the version alias you can do so by leveraging the --branch option.

Create a branch of gh-pages (let’s call it update-gh-pages for this example) and issue the following:

mike alias docs-<version> latest --update-aliases --push --branch update-gh-pages

mike set-default --push latest --branch update-gh-pages

Now you should be able to open a PR with target branch gh-pages and update the aliases and defaults.