Release Guide¶

This document describes the steps for making a new SeQuant release.

Version Numbering¶

SeQuant uses semantic versioning: MAJOR.MINOR.MICRO with an optional prerelease identifier (e.g., alpha.1, beta.2, rc.1). The canonical version is defined in the top-level CMakeLists.txt and propagated automatically to all other locations via CMake template substitution.

Files to Update¶

Only two files require manual version updates:

CMakeLists.txt (lines ~37–40) — the source of truth:
```
set(SEQUANT_MAJOR_VERSION 2)
set(SEQUANT_MINOR_VERSION 3)
set(SEQUANT_MICRO_VERSION 0)
set(SEQUANT_PRERELEASE_ID )
```
Clear SEQUANT_PRERELEASE_ID for a final release, or set it to e.g. alpha.1 for a pre-release.
CITATION.cff (lines ~5–6):
```
version: 2.3.0
date-released: 2026-03-15
```
Update both the version string and the release date.

Auto-populated Files (no manual edits needed)¶

The following files use @SEQUANT_VERSION@ (or similar) placeholders that CMake fills in at configure time:

SeQuant/version.hpp.in — C++ version macros
cmake/sequant-config.cmake.in — installed CMake package config
doc/.doxygen/Doxyfile.in — Doxygen project number
doc/.sphinx/conf.py.in — Sphinx docs version

Release Checklist¶

Create a release branch (if not already on one), e.g. the 2.3.Z releases would live on the v2.3.x branch:
```
git checkout -b vX.Y.x master
```
Bump versions in CMakeLists.txt and CITATION.cff as described above.

Commit the version bump:

git add CMakeLists.txt CITATION.cff
git commit -m "bump version to X.Y.Z"

Verify the build — ensure the project configures, builds, and tests pass:
```
cmake -B build -S .
cmake --build build
ctest --test-dir build
```
Tag the release:
```
git tag -a vX.Y.Z -m "SeQuant X.Y.Z"
```

Push the branch and tag:

git push origin vX.Y.Z
git push origin --tags

Create a GitHub release from the tag at github.com/ValeevGroup/SeQuant/releases. Use the auto-generated release notes as a starting point.
Post-release: on master, bump the version to the next development pre-release (e.g., X.Y+1.0 with SEQUANT_PRERELEASE_ID set to alpha) and update CITATION.cff accordingly.