Switch to calendar versioning: YY.N[.P]

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

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")

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. 

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@"

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
 #

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 <https://semver.org/>`_: ``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 <https://calver.org/>`_: ``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,18 +84,20 @@ 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
    `github.com/ValeevGroup/SeQuant/releases <https://github.com/ValeevGroup/SeQuant/releases>`_.
    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``.

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(<target> 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 <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. 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.