4. The Release Process

This is a rough overview of OpenSim Creator’s release process - mostly intended as internal documentation for the development team.

OpenSim Creator aims to have a 1-2 month release cadence - even if no major changes occur in that window. This ensures that at least one tested, libASANed, linted, and manually-checked release of OpenSim Creator available with that cadence and ensures that the release pipeline is regularly exercised and ready to roll when quick hotfixes are required.

4.1. Release Checklist (Markdown)

This checklist outlines the manual steps taken to produce a release of OpenSim Creator, it’s usually copied into a GitHub issue:

- [ ] Create an issue called something like `Release XX.xx.pp`
- [ ] Copy this checklist into it
- [ ] Bump OSC's version number in `CMakeLists.txt` (`project`)
- [ ] Clean-build a debug (+ libASAN) version of OSC on Ubuntu 24 (debugging os).
      See `scripts/build_linux_debugging.sh` etc. for a guide for this.
- [ ] Ensure the test suite passes with the debug build
  - [ ] Optionally, also ensure the test suite passes under valgrind (see: `scripts/build_linux_valgrind.sh`)
- [ ] Manually spot-check new changes with the debug+ASAN build
- [ ] Fix all bugs/problems found during the above steps
- [ ] Update `CHANGELOG.md` sections such that the current `Unreleased`
      section becomes `XX.xx.pp` and add a new `Unreleased` section
      above that
- [ ] Commit any fixes to CI and ensure CI passes
- [ ] Tag+push the commit as a release
- [ ] Rebase any currently-active feature branches to this commit (don't allow stale branches)
- [ ] Bump OSC's version number in `CMakeLists.txt` (`project`) to `$VERSION+1`
- [ ] Download artifacts from the tagged commit CI build
  - [ ] Also, create a source tarball with `./scripts/bundle_sources.sh $VERSION`
  - [ ] Also, build a MacOS ARM64 build locally from the release and upload it
- [ ] Clean-install artifacts on development machines, ensure they install as-expected
- [ ] Unzip/rename any artifacts (see prev. releases)
- [ ] Create new release on github from the tagged commit
  - [ ] Upload all artifacts against it
  - [ ] Write a user-friendly version of CHANGELOG that explains the release's
    changes
- [ ] Update Zenodo with the release
  - [ ] This usually happens automatically, via a webhook in Zenodo
  - [ ] Otherwise, it requires @adamkewley's GitHub login to publish
    the generated draft from Zenodo
- [ ] Update + commit the repository with the Zenodo release details:
  - [ ] Use `bump_zenodo_details.py` to automatically do this
  - [ ] Ensure `codemeta.json` is up-to-date
  - [ ] Ensure `CITATION.cff` is up-to-date
  - [ ] Ensure `README.md` is up-to-date
- [ ] Ensure the entire repository, incl. all tags, is pushed to the official
      TU Delft mirror at https://gitlab.tudelft.nl/computationalbiomechanicslab/opensim-creator
- [ ] Update `docs.opensimcreator.com` to host the documentation
  - [ ] **Note**: this requires appropriate credentials for `docs.opensimcreator.com`
  - [ ] Build the docs yourself, or get the CI build of them
  - [ ] Upload with (e.g.) `rsync -avz --delete build/ docs.opensimcreator.com:/var/www/docs.opensimcreator.com/manual/en/latest/`
- [ ] Update `www.opensimcreator.com` with a basic announcement news post
  - [ ] **Note**: this requires appropriate SSH credentials for `www.opensimcreator.com`
  - [ ] Edit https://github.com/ComputationalBiomechanicsLab/opensim-creator-site appropriately
  - [ ] Upload with (e.g.): `rsync -avz public/ www.opensimcreator.com:/var/www/opensimcreator.com/`
- [ ] Update `files.opensimcreator.com/releases` with appropriate release artifacts
  - [ ] Upload with (e.g.): `rsync --delete --exclude .git/ -avz files.opensimcreator.com/ files.opensimcreator.com:/var/www/files.opensimcreator.com/`
- [ ] (optional) Update social media:
  - [ ] LinkedIn
  - [ ] Twitter
  - [ ] Bluesky
  - [ ] SimTK
  - [ ] Reddit (occasionally)
  - [ ] https://research-software-directory.org/ (usually this is automatic)

4.2. Release Build Matrix

Here is a top-level overview of the architectures/platforms/compilers that we use to produce OpenSim Creator’s releases. Feature developers don’t need to use exactly the same combinations (it’s healthy to exercise other combinations!) but these are the ones that are used during a release, so everything must eventually compile+pass with these combinations:

Table 4.1 OpenSim Creator’s Release Matrix. The exact way in which this matrix is built is outlined in the .github/ directory in OpenSim Creator’s source repository.

Architecture	Target Operating System	C++ Compiler
amd64	Windows 10 (>= v1507)	MSVC 19.43.34808.0 (VS 17.13.358, Windows SDK 10.0.26100.0)
amd64	MacOS 14.5	XCode 15.4
arm64	MacOS 14.5	XCode 15.4
amd64	Ubuntu 22.04	gcc 12.3.0 (gcc-12, installed via apt)

Notably, these toolchains do not have 100 % coverage of the C++20/23 language or library specifications. So check C++ Compiler Support if you plan on using a newer C++ features.

4.2.1. Release Matrix Upgrades/Changes

Because it’s exhausting to constantly update/change build pipelines (even if I’m particularly desperate for std::format support 😉 - looking at you, gcc-12), this build matrix should only be checked/updated occasionally. The next scheduled times that we will check this matrix are:

• October 2025, which is when Windows 10 support is EOL. The build system will be upgraded to target Windows 11.

• May 2026, which is when Ubuntu 22.04 is EOL for unpaid customers. The build system will then be upgraded to target Ubuntu 24.04.

• September 2026, which is when MacOS 14 is likely to be unsupported. The build system will then be upgraded to target MacOS 15 (Sequoia).

The build matrix might also change because of upgrades/changes to the CI server. Those changes will (hopefully) be mostly limited to minor bugfix upgrades.