diff --git a/CITATION.cff b/CITATION.cff
index acd9548978c..a05adf98bda 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -2,7 +2,7 @@ cff-version: 1.2.0
title: "SeQuant: Symbolic Tensor Algebra in C++"
message: "If you use this software, please cite the preferred-citation article below."
type: software
-version: 2.3.0-alpha
+version: 26.2-alpha
date-released: 2026-xx-yy
license: LGPL-3.0
repository-code: https://github.com/ValeevGroup/SeQuant
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6ff6c0d4bc0..654a041fac7 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -33,12 +33,16 @@ FetchContent_Declare(
FetchContent_MakeAvailable(vg_cmake_kit)
list(APPEND CMAKE_MODULE_PATH "${vg_cmake_kit_SOURCE_DIR}/modules")
-# Set SeQuant version
-set(SEQUANT_MAJOR_VERSION 2)
-set(SEQUANT_MINOR_VERSION 3)
-set(SEQUANT_MICRO_VERSION 0)
+# Set SeQuant version: calendar versioning YY.N[.P][-id], where N counts the
+# releases within the year starting from 0 and P is the patch level
+set(SEQUANT_YEAR_VERSION 26) # two-digit year
+set(SEQUANT_YMAJOR_VERSION 2) # zero-based release counter within the year
+set(SEQUANT_PATCH_VERSION 0) # patch level; 0 is omitted from the version string
set(SEQUANT_PRERELEASE_ID alpha)
-set(SEQUANT_VERSION "${SEQUANT_MAJOR_VERSION}.${SEQUANT_MINOR_VERSION}.${SEQUANT_MICRO_VERSION}")
+set(SEQUANT_VERSION "${SEQUANT_YEAR_VERSION}.${SEQUANT_YMAJOR_VERSION}")
+if (SEQUANT_PATCH_VERSION GREATER 0)
+ string(APPEND SEQUANT_VERSION ".${SEQUANT_PATCH_VERSION}")
+endif ()
if (SEQUANT_PRERELEASE_ID)
set(SEQUANT_EXT_VERSION "${SEQUANT_VERSION}-${SEQUANT_PRERELEASE_ID}")
else (SEQUANT_PRERELEASE_ID)
@@ -116,7 +120,7 @@ set(SEQUANT_INSTALL_INCLUDEDIR "include"
CACHE PATH "SeQuant INCLUDE install directory")
set(SEQUANT_INSTALL_LIBDIR "lib"
CACHE PATH "SeQuant LIB install directory")
-set(SEQUANT_INSTALL_SHAREDIR "share/sequant/${SEQUANT_MAJOR_VERSION}.${SEQUANT_MINOR_VERSION}.${SEQUANT_MICRO_VERSION}"
+set(SEQUANT_INSTALL_SHAREDIR "share/sequant/${SEQUANT_VERSION}"
CACHE PATH "SeQuant SHARE install directory")
set(SEQUANT_INSTALL_DATADIR "${SEQUANT_INSTALL_SHAREDIR}/data"
CACHE PATH "SeQuant DATA install directory")
diff --git a/README.md b/README.md
index 31a31ffd602..91b35341968 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,14 @@ endif()
target_link_libraries(your_executable_or_library_target PUBLIC SeQuant::SeQuant)
```
+## Versioning
+
+SeQuant uses [calendar versioning](https://calver.org/): `YY.N` for a release, where `YY` is the two-digit year and `N`
+counts the releases within that year starting from 0, and `YY.N.P` for the `P`-th patch release of `YY.N`; e.g. `26.2`
+is the third release of 2026 and `26.2.1` its first patch release. Releases up to `2.2.0` used
+[semantic versioning](https://semver.org/); `26.2` is the first calendar-versioned release. See the
+[release guide](https://valeevgroup.github.io/SeQuant/maintainer/release.html) for details.
+
## Developers
The [Valeev Research Group (VRG)](https://valeevgroup.github.io) in the Department of Chemistry at Virginia Tech kickstarted the initial design and development of SeQuant. The ongoing development of SeQuant is driven by major [contributions](https://github.com/ValeevGroup/SeQuant/graphs/contributors) from VRG and the [Köhn Group](https://www.itheoc.uni-stuttgart.de/research/koehn) in the Department of Theoretical Chemistry at University of Stuttgart.
diff --git a/SeQuant/version.hpp.in b/SeQuant/version.hpp.in
index e52962ee53f..a5d3aa16281 100644
--- a/SeQuant/version.hpp.in
+++ b/SeQuant/version.hpp.in
@@ -5,17 +5,17 @@
#ifndef SEQUANT_SRC_SEQUANT_VERSION_H_IN_H
#define SEQUANT_SRC_SEQUANT_VERSION_H_IN_H
-/* SeQuant version X.Y.Z-id */
+/* SeQuant version YY.N[.P] (calendar versioning; the prerelease id is separate) */
#define SEQUANT_VERSION "@SEQUANT_VERSION@"
-/* SeQuant major version */
-#define SEQUANT_MAJOR_VERSION @SEQUANT_MAJOR_VERSION@
+/* SeQuant year version: two-digit year */
+#define SEQUANT_YEAR_VERSION @SEQUANT_YEAR_VERSION@
-/* SeQuant minor version */
-#define SEQUANT_MINOR_VERSION @SEQUANT_MINOR_VERSION@
+/* SeQuant year-major version: zero-based release counter within the year */
+#define SEQUANT_YMAJOR_VERSION @SEQUANT_YMAJOR_VERSION@
-/* SeQuant micro version */
-#define SEQUANT_MICRO_VERSION @SEQUANT_MICRO_VERSION@
+/* SeQuant patch version: patch level, 0 if none */
+#define SEQUANT_PATCH_VERSION @SEQUANT_PATCH_VERSION@
/* SeQuant prerelease id */
#define SEQUANT_PRERELEASE_ID "@SEQUANT_PRERELEASE_ID@"
diff --git a/cmake/sequant-config.cmake.in b/cmake/sequant-config.cmake.in
index b0f9aa58bc7..61207eb4c1d 100644
--- a/cmake/sequant-config.cmake.in
+++ b/cmake/sequant-config.cmake.in
@@ -2,8 +2,8 @@
# This will define the following CMake cache variables
#
# SEQUANT_FOUND - true if SeQuant library were found
-# SEQUANT_VERSION - the x.y.z SeQuant version
-# SEQUANT_EXT_VERSION - the x.y.z(-buildid) SeQuant version, where the (optional) buildid is smth like beta.3
+# SEQUANT_VERSION - the YY.N[.P] SeQuant version
+# SEQUANT_EXT_VERSION - the YY.N[.P](-buildid) SeQuant version, where the (optional) buildid is smth like beta.3
#
# and the following imported targets
#
diff --git a/doc/maintainer/release.rst b/doc/maintainer/release.rst
index 1ee9f860dc4..e7378c3da31 100644
--- a/doc/maintainer/release.rst
+++ b/doc/maintainer/release.rst
@@ -8,9 +8,14 @@ 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.
+SeQuant uses `calendar versioning `_: ``YY.N`` for a release and ``YY.N.P`` for a patch release,
+with an optional prerelease identifier (e.g., ``alpha.1``, ``beta.2``, ``rc.1``). ``YY`` is the two-digit year, ``N``
+counts the releases within that year starting from 0, and ``P`` counts the patch releases of ``YY.N`` starting from 1.
+E.g., the third release of 2026 is ``26.2``, its first patch release is ``26.2.1``, and the first release of 2027 is
+``27.0``. Releases up to ``2.2.0`` used semantic versioning; ``2.1.0`` and ``2.2.0``, both released in 2026, count as
+the first two releases of that year, so the first calendar-versioned release is ``26.2``. 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
---------------
@@ -21,19 +26,20 @@ Only **two files** require manual version updates:
.. code-block:: cmake
- set(SEQUANT_MAJOR_VERSION 2)
- set(SEQUANT_MINOR_VERSION 3)
- set(SEQUANT_MICRO_VERSION 0)
+ set(SEQUANT_YEAR_VERSION 26) # two-digit year
+ set(SEQUANT_YMAJOR_VERSION 2) # zero-based release counter within the year
+ set(SEQUANT_PATCH_VERSION 0) # patch level; 0 is omitted from the version string
set(SEQUANT_PRERELEASE_ID )
Clear ``SEQUANT_PRERELEASE_ID`` for a final release, or set it to e.g. ``alpha.1`` for a pre-release.
+ ``SEQUANT_PATCH_VERSION`` stays ``0`` for a ``YY.N`` release and is set to ``P`` for the ``YY.N.P`` patch release.
2. **CITATION.cff** (lines ~5--6):
.. code-block:: yaml
- version: 2.3.0
- date-released: 2026-03-15
+ version: 26.2
+ date-released: 2026-11-15
Update both the version string and the release date.
@@ -50,11 +56,12 @@ The following files use ``@SEQUANT_VERSION@`` (or similar) placeholders that CMa
Release Checklist
-----------------
-1. **Create a release branch** (if not already on one), e.g. the 2.3.Z releases would live on the v2.3.x branch:
+1. **Create a release branch** (if not already on one), e.g. the 26.2 release and its 26.2.P patch releases would
+ live on the v26.2.x branch:
.. code-block:: bash
- git checkout -b vX.Y.x master
+ git checkout -b vYY.N.x master
2. **Bump versions** in ``CMakeLists.txt`` and ``CITATION.cff`` as described above.
@@ -63,7 +70,7 @@ Release Checklist
.. code-block:: bash
git add CMakeLists.txt CITATION.cff
- git commit -m "bump version to X.Y.Z"
+ git commit -m "bump version to YY.N[.P]"
4. **Verify the build** — ensure the project configures, builds, and tests pass:
@@ -77,13 +84,13 @@ Release Checklist
.. code-block:: bash
- git tag -a vX.Y.Z -m "SeQuant X.Y.Z"
+ git tag -a vYY.N[.P] -m "SeQuant YY.N[.P]"
6. **Push the branch and tag**:
.. code-block:: bash
- git push origin vX.Y.Z
+ git push origin vYY.N.x
git push origin --tags
7. **Create a GitHub release** from the tag at
@@ -91,4 +98,6 @@ Release Checklist
Use the auto-generated release notes as a starting point.
8. **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.
+ (``YY.N+1``, or ``YY+1.0`` if the next release will be the first of a new year, with ``SEQUANT_PRERELEASE_ID`` set
+ to ``alpha``) and update ``CITATION.cff`` accordingly. A patch release ``YY.N.P`` is made on the ``vYY.N.x``
+ branch and tagged ``vYY.N.P``; it does not change the version on ``master``.
diff --git a/doc/user/getting_started/installing.rst b/doc/user/getting_started/installing.rst
index 8e1674b50b4..e7b10e43269 100644
--- a/doc/user/getting_started/installing.rst
+++ b/doc/user/getting_started/installing.rst
@@ -158,3 +158,14 @@ provide 8 MB). SeQuant's own executables are therefore linked with :code:`/STACK
SeQuant must be linked with an equivalent stack reserve too, e.g. via
:code:`target_link_options( PRIVATE /STACK:8388608)`. This reserve is the default for every thread of the
program; threads created with an explicit stack size that call into SeQuant need a comparable size.
+
+
+Versioning
+----------
+
+SeQuant uses `calendar versioning `_: ``YY.N`` for a release, where ``YY`` is the two-digit year
+and ``N`` counts the releases within that year starting from 0, and ``YY.N.P`` for the ``P``-th patch release of
+``YY.N``; e.g. ``26.2`` is the third release of 2026 and ``26.2.1`` its first patch release. Releases up to ``2.2.0``
+used `semantic versioning `_; ``26.2`` is the first calendar-versioned release. Since a version
+is just a dot-separated sequence of integers, ``find_package(SeQuant 26.2)`` and similar version requirements work as
+usual. See :ref:`release-guide` for details.