We have a goal of simultaneously serving multiple versions of the docs. This means that there are multiple versions of the docs existing next to each other in the docs repo. This differs from what is normal, where only a single version exists in the repo at a time and a git tag is created to reference old versions.
The versions that exist together are major or minor versions (e.g. v1.1, v1.2 and v2.0). There only exists a single patch version (or pre-release alphas, betas and release candidates) for each major/minor version. When we do a new patch release, the updates are made in-place.
- Ensure master docs are passing semaphore tests.
- Check out latest master locally.
These steps are for creating a new major/minor release, with the expectation that a release candidate will be created, published and tested before the final release is announced.
- Run release-scripts/do_release.py to copy master directory to the new version directory
- Add the new version to
_data/versions.yaml
(add the date of the release in the description)- Add new versions that are a release candidate to the end of the file. If a release is added to the top of the file it will become the 'Latest Release'.
- Add a section in
_config.yaml
so thatpage.version
will be set correctly in the new subdirectory:- scope: path: vX.Y values: version: vX.Y
- Update the
RELEASE_STREAM
variable at the top of calico_node/Makefile to the new major/minor version. - Test the changes locally then open a pull request, make sure it passes CI and get it reviewed.
- Create a git tag, docker images, and release file by running
make -C calico_node release
. Follow the instructions to push the images but DO NOT PUSH THE TAG YET. - Now merge the PR - this will cause the live docs site to be updated (after a few minutes).
- Push the tag.
- Create a GitHub release on the Calico repo, and upload the release file (calico_node/release-.tgz)
- Edit the Calico Docs Custom Search Engine.
- Navigate to: search engine -> Search Features -> Refinements -> Add
- Add a new refinement name: vX.Y
- Navigate to: Setup -> Basics
- Under "Sites to search", select "Add", for the url use
docs.projectcalico.org/vX.Y
- Choose vX.Y from the "Label" dropdown.
- Edit
_config_dev.yml
to exclude the previous release.
- Add a new
<option>
entry to the<span class="dropdown">
in_layouts/docwithnav.html
file. This step should NOT be performed until testing of the release is complete. - Modify the redirect in
/index.html
to point to your new release.. - Move the section for the release in
_data/versions.yaml
to the top of the file so that it will be the 'Latest Release'. - Run
make add_redirects_for_latest VERSION=vX.Y
to update the redirects. - Test the changes locally then open a pull request, make sure it passes CI and get it reviewed.
- Create a git tag, docker images, and release file by running
make -C calico_node release
. Follow the instructions to push the images but DO NOT PUSH THE TAG YET. - Now merge the PR - this will cause the live docs site to be updated (after a few minutes).
- Push the tag.
- Create a GitHub release on the Calico repo, and upload the release file (calico_node/release-.tgz)
Patch releases shouldn't include any new functionality, just bug fixes (expect during pre-release testing).
- Add the new version to
_data/versions.yaml
(Remember to add the date in the description) - Test the changes locally then open a pull request, make sure it passes CI and get it reviewed.
- Create a git tag, docker images, and release file by running
make -C calico_node release
. Follow the instructions to push the images but DO NOT PUSH THE TAG YET. - Now merge the PR - this will cause the live docs site to be updated (after a few minutes).
- Push the tag.
- Create a GitHub release on the Calico repo, and upload the release file (calico_node/release-.tgz)