Release process

Steps to perform a release

The following instructions assume that you have sufficient permissions to draft and publish releases (contributor rights -- maintainers do not have additional privileges, so any contributor can do a release following these steps).

• If doing a release together with a liboqs release,
  • run python3 oqs-template/generate.py && ./scripts/do_code_format.sh --no-dry-run: if code changes become visible, be sure to do a PR with this before the release; be sure to have code properly formatted as per coding style documentation.
  • store and safeguard "generate.yml" with the suitable liboqs version name suffixed such as to permit correct future execution of "fullbuild.sh" with LIBOQS_BRANCH set.
• If doing a release independent of a liboqs release, be sure to be able to generate code from the stated supported liboqs release "a.b.c" (by running LIBOQS_BRANCH=a.b.c ./scripts/fullbuild.sh -F && ./scripts/runtests.sh -V).
• Check all CI tests pass.
• Check ./scripts/release-test.sh passes on latest openssl and supported/latest liboqs release(s).
• Update "OQSPROVIDER_VERSION_TEXT" in CMakeLists.txt.
• Update SECURITY.md to state new supported release ID.
• Update supported liboqs version in CI binary generator files in ".github/workflows" for Linux, MacOS, Windows (if only a specific liboqs version is to be supported, rather than "main", e.g., in case of security hotfix in liboqs)
• Open github release UI by clicking on "Releases" and "Draft a new release".
• Select release tag matching contents of OQSPROVIDER_VERSION_TEXT and click "Generate release notes".
• Complete generated notes with high-level release description making the sure the CMakelists version number, git tag name, and release notes version numbers all match; do not yet click on "Publish release".
• Copy full release description to the top of RELEASES.md; delete the latest entry to RELEASES.md and repeat the process as often as necessary upon subsequent edits to the description.
• Add and commit this update to a PR branch (clearing all caches in Actions recommended) targeting main.
• Create and publish a release candidate pre-release in the GitHub release UI with the tag x.y.z-rc1 (e.g., 0.6.1-rc1). "rc1" should be bumped to "rc2", "rc3", etc. if multiple release candidates are required (all on the same PR branch).
• A minimal RC acceptance condition is that nginx and curl images build and interoperate OK (part of automated CI downstream testing); a more complete acceptance condition is that the openssl external test integration passes.
• When the release candidate is ready for release (usually agreed upon by consensus in an OQS meeting), remove all "rc" references from the PR branch and request PR approval
• After this PR has been approved and landed, create and publish the final release targeting this commit in "main"
• After this is done, CI will again trigger downstream creation of integration docker images, e.g., curl and nginx in the oqs-demos sub project. It is highly advisable that the images created at this moment are suitably tagged with the same release version.
• Next, upgrade "OQSPROVIDER_VERSION_TEXT" in CMakeLists.txt to next "-dev" version for continued development; also update RELEASE.md to match.
• Again, as maintainers don't have admin privileges, create yet another PR with this targeting main. After this has been approved and landed, development (PRs) can commence as usual; note that the docker images will be automatically re-created and the specific version matching the release ID will be over-written (unless tagged as per the previous step). Automation for this would be desirable.

Website updates

After the release, create a pull request for the OQS website updating the version log and adding a news item to the front page