The Release Process

The Release Process#

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

OPynSim aims to have a 1-3 month release cadence - even if no major changes occur in a release window. This ensures that at least one commit of OPynSim’s source code is tested, libASANed, linted, manually-checked, etc. every 1-3 months.

Release Checklist (Markdown)#

This release checklist is in markdown so that it can be copied + pasted into websites like GitHub.

## Prepare, Test, Package

- [ ] Create an issue called something like `Release XX.xx.pp`
- [ ] Copy this checklist into it
- [ ] Bump the VERSION tag in the top-level `CMakeLists.txt` file to `XX.xx.pp`
- [ ] On a Linux machine, clean-build the `ErrorCheck` configuration `cd third_party/ && cmake --workflow --preset ErrorCheck && cd - && cmake --workflow --preset ErrorCheck`
- [ ] Ensure the `ErrorCheck` build + tests all pass
- [ ] Manually spot-check any new changes with the `ErrorCheck` build
- [ ] Fix all bugs/problems/lints found during the above steps
- [ ] Commit the fixes to CI and ensure CI passes
- [ ] Download CI artifacts for all supported platforms. Install them on all applicable test/development machines. Manually spot-check that they install, work, etc.
- [ ] Update  `CHANGELOG.md`:
  - [ ] Move sections around such that `Unreleased` becomes `XX.xx.pp`, add a new (empty) `Unreleased` section at the top.
  - [ ] Write a very short summary paragraph at the top of the `XX.xx.pp` section, for use in GitHub, website, etc.
- [ ] Push the `CHANGELOG.md` update commit (e.g. "Update CHANGELOG.md for XX.xx.pp")
- [ ] Tag the commit as `v${VERSION}`
- [ ] Rebase any active branches onto the `main` branch so that all branches are at-least compatible with the latest release, or delete the branches if they are stale.
- [ ] Collect all build artifacts:
  - [ ] `opynsim-${VERSION}-cp312-abi3-macosx_14_5_arm64.whl`
  - [ ] `opynsim-${VERSION}-cp312-abi3-win_amd64.whl`
  - [ ] `opynsim-${VERSION}-cp312-abi3-manylinux_2_28_x86_64.whl`
  - [ ] `opynsim-${VERSION}-docs.tar.xz`: E.g. `tar cvzf opynsim-${VERSION}-docs.tar.xz -C ${DOCS_HTML_DIR} --transform="s,^,opynsim-${VERSION}-docs/," *`.
  - [ ] `opynsim-${VERSION}-src.tar.xz`: E.g. `git archive --format=tar --prefix=opynsim-${VERSION}/ v${VERSION} | xz -c > "opynsim-${VERSION}-src.tar.xz"`.

## Publish

- [ ] Create a GitHub release from the tagged commit
  - [ ] Upload all artifacts build artifacts against the release
  - [ ] Copy + paste the release summary paragraph from `CHANGELOG.md` as the release description
- [ ] Upload wheels to PyPi
  - [ ] Set `TWINE_USERNAME` and `TWINE_PASSWORD` (stored on developer's keychain)
  - [ ] Run `./scripts/deploy_pypi.py WHEEL_FILES` (or similar)
- [ ] Update Zenodo with the release
  - [ ] This should happen automatically, because Zenodo is linked to @adamkewley, which
        and has linked/mirrored organizational OAuth access for OPynSim setup at the
        user-level.
- [ ] TODO: Update `README.md` with Zenodo release details
- [ ] Ensure the entire repository is pushed/mirrored to the official TU Delft mirror:
  - [ ] `git remote add tud https://gitlab.tudelft.nl/opynsim/opynsim.git`
  - [ ] `git push tud --all`
  - [ ] `git push tud --tags`
- [ ] Ensure all build artifacts are uploaded to `files.opynsim.eu/releases`:
  - [ ] `rsync -avz release-binaries/* files.opynsim.eu:/var/www/files.opynsim.eu/releases/`
- [ ] Upload built documentation to `docs.opynsim.eu`
  - [ ] `rsync -avz --delete ${DOCS_HTML_DIR}/ docs.opynsim.eu:/var/www/docs.opynsim.eu/manual/en/latest`
- [ ] Ensure repo syncs with research-software-directory.org

## Announce Release

- [ ] Make short announcement posts on social media:
  - [ ] LinkedIn
  - [ ] Bluesky
  - [ ] SimTK

- [ ] Ensure any collaborators/researchers involved with the release cycle are
      informed of the release.
Contents