Prepare and Deploy#

Note

The steps described in this document are intended for maintainers of the simtools project.

Simtools releases follow the Semantic Versioning 2.0.0 guidelines with a version string format of vMAJOR.MINOR.PATCH (e.g., v2.1.3). Note that simtools is named gammasimtools on PyPi and in the conda.

Release Preparation#

Open a release candidate pull request from a branch named <version string>-rc (e.g., v2.1.3-rc). To use the release-candidate template, append the query parameters ?quick_pull=1&template=release-candidate.md to the compare URL. For example:

https://github.com/gammasim/simtools/compare/main...v2.1.3-rc?quick_pull=1&template=release-candidate.md

The template is the Release Candidate pull request template, which includes a checklist of items to complete before the release. This should be the final pull request before a release.

Before merging the release candidate, confirm that the dependency catalog validates. Add image digests and source revisions for a release that requires immutable build inputs. See Dependency versions and provenance.

Release and Deploy#

  1. Prepare a GitHub release with the version number and a summary of the changes (simtools release pages) and release.

  2. Pypi deployment is triggered automatically by the CI/CD pipeline via the pypi.yml workflow.

  3. Container images are built and tagged automatically with the version number, and pushed to gammasim/simtools via the build-simtools-production-images.yml workflow.

  4. A DOI is issued automatically by Zenodo, see the simtools Zenodo page.

The default branch’s docs/_static/switcher.json selects the published documentation versions. Each release workflow stores its documentation as docs-site.tar.gz on the corresponding GitHub release. Each switcher entry requires version and an https url. Add a version to the switcher only when its archive exists or when publishing that version. Remove an entry to omit its documentation from the next site deployment; the release asset remains available for restoration. Run the documentation workflow manually on the default branch to apply switcher changes. The root serves the latest stable documentation when its release archive exists; otherwise a manual run uses the current default branch build until a stable release provides an archive. The test resource dashboard is included in each deployment.

GitHub Pages must be configured to use GitHub Actions as its publishing source, and the github-pages environment must allow deployments from the default branch and from release tags (v*). The benchmark-data draft release stores the two latest benchmark snapshots as release assets outside Git. Its tag points to source code; generated benchmark data is not committed. A new installation starts a fresh benchmark history.