Skip to content

Release process

Jump to bottom
Bruce edited this page Nov 12, 2025 · 25 revisions

Code change

The following files are to be updated

  • The top-level CMakeLists.txt:
    • Update the following variables: OQS_VERSION_TEXT, OQS_VERSION_MAJOR, OQS_VERSION_MINOR, OQS_VERSION_PATCH, OQS_VERSION_PRE_RELEASE
      • For releases, OQS_VERSION_PRE_RELEASE should be the empty string in CMakeLists.txt, resulting in it being unset in oqsconfig.h
      • Other values of OQS_VERSION_PRE_RELEASE: -dev for code on the main branch in between releases; -rc1 etc. for release candidates
    • Update SOVERSION if applicable
  • RELEASE.md - Update version number, fill in text
  • SECURITY.md - Update support level, latest security status

Sanity check for version number:

# from $LIBOQS_DIR
mkdir build
cmake -Bbuild .
grep "#define OQS_VERSION_TEXT" build/include/oqs/oqsconfig.h
# check the version text displays the intended version

Additional tests

Idempotence of copy_from_upstream

Running the script to include upstream algorithm code should not result in any changes.

Constant time

Most notably, constant time tests need to be executed locally without skipping any algorithms (as is done to allow CCI task weekly to pass), i.e., run python3 -m pytest --verbose --numprocesses=auto tests/test_constant_time.py after building liboqs via cmake -GNinja -DOQS_DIST_BUILD=OFF -DOQS_OPT_TARGET=haswell -DCMAKE_BUILD_TYPE=Debug -DOQS_ENABLE_TEST_CONSTANT_TIME=ON .. and cmake -GNinja -DOQS_DIST_BUILD=OFF -DOQS_OPT_TARGET=generic -DCMAKE_BUILD_TYPE=Debug -DOQS_ENABLE_TEST_CONSTANT_TIME=ON ...

Performance

noregress.sh script has been deprecated in favor of GitHub Actions KEM benchmark and SIG benchmark. They can be triggered manually on a specified branch and will automatically test for performance regression.

Subprojects

openssl (oqs-provider)

For subproject oqs-provider, a specific release-test script should be run on a suitably powerful (many-core) machine: It enables all algorithm combinations and tests those. This test will run automatically in CI once a release candidate is tagged. The CI workflow will run using the liboqs release candidate tag and oqs-provider branch (or tag) <liboqs RC tag>-tracker. If the latter does not exist, the main branch of oqs-provider will be used instead. For example, if the liboqs release candidate tag is 0.9.3-rc1, the CI workflow will attempt to build liboqs from the tag 0.9.3-rc1 and oqs-provider from the branch (or tag) 0.9.3-rc1-tracker. Before publishing the liboqs release candidate tag, it is recommended to create an appropriate -tracker branch, which can then be converted into an oqs-provider release candidate if so desired.

# example commands to run `oqs-provider`'s release tests in a non-CI environment
git clone https://github.com/open-quantum-safe/oqs-provider
cd oqs-provider
export LIBOQS_BRANCH="x.y.z-rc-branch"
export OPENSSL_BRANCH="openssl-3.2.2"
git clone [email protected]:open-quantum-safe/liboqs.git --single-branch --branch $LIBOQS_BRANCH --depth 1
# set up Python environment, such as with pyenv + venv
pip install --upgrade pip wheel setuptools pytest pytest-xdist psutil jinja2 PyYAML tabulate
./scripts/release-test.sh

oqs-demos

Dockerfiles contain hard-coded OQS version numbers that need updating upon release to avoid them falling out of step with progress. Furthermore, upon build, Docker images resulting from the build in oqs-demos should be tagged to the same version number as liboqs as and when they have been built and deployed by the CCI automation. Sample command: docker tag openquantumsafe/curl:latest openquantumsafe/curl:0.5. The binary image of chromium has to be built in a bespoke ubuntu image with all prerequisites as documented. Be sure to set -DOQS_DIST_BUILD=ON to execute the resultant binary on any CPU. There presently is no docker-based build infrastructure available to generate and test-run this binary.

Interop test server

Subsequent a successful new release, follow the documentation at oqs-demos/nginx/fulltest to install a new interop test server. Possible procedure:

  • Update version tags of liboqs and oqs-provider in build-ubuntu.sh
  • build server and certificates
  • deploy to actual server All three steps could be performed at once when executed at the configured test server (test.openquantumsafe.org).

Downstream tagging

After a release candidate (RC) passed all internal and downstream project tests, downstream projects --unless following their own release strategy-- should be tagged, too.

Website updates

Create a pull request for the OQS website updating the liboqs algorithm version in submodule (_include/liboqs), as well as the version log and adding a news item to the front page

Clone this wiki locally