From e5218635b1666f194eb4938daa1a9721397a1e56 Mon Sep 17 00:00:00 2001 From: "Ralf W. Grosse-Kunstleve" Date: Tue, 22 Sep 2026 10:24:04 -0700 Subject: [PATCH] Add "Git-derived version lifecycle" section in AGENTS.md --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 05f4d9b780d..381cb26a5ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,6 +12,38 @@ guide for package-specific conventions and workflows. - `cuda_core/`: High-level Pythonic CUDA APIs built on top of bindings. - `cuda_python/`: Metapackage and docs aggregation. +# Git-derived version lifecycle + +Package versions are derived from reachable Git tags by `setuptools-scm`. +Allow its standard tag parsing and version progression to govern versions; do +not add custom tag parsing or manufacture a version when an appropriate tag is +already reachable from the commit being built. + +For each package tag namespace and target release `X.Y.Z`: + +- Reserve `aN` (alpha) tags for internal purposes. Do not use them as public + release milestones. +- Before the first retained tag for a new version line exists, an internal + preview build may create a local, lightweight `X.Y.Za0.dev0` tag at a + validated ancestor. The synthetic tag must remain local to the build and + must never be pushed. +- Use `X.Y.Za0` for the first retained internal milestone. Untagged descendants + then naturally become `X.Y.Za1.devN` under the standard `setuptools-scm` + version scheme. A later exact `aN` milestone requires an explicit decision; + do not create a tag for every pull request or build. +- When any tag for `X.Y.Z` in the package's namespace is reachable, do not + create a synthetic tag. Let `setuptools-scm` derive the version from the + existing history. +- Treat pushed tags as immutable. Correct an unsuitable tagged state with a + new versioned milestone rather than moving or replacing the existing tag. + +Use the package's established tag namespace, such as `vX.Y.Z...` for +`cuda-bindings` and `cuda-python`, `cuda-core-vX.Y.Z...` for `cuda-core`, and +`cuda-pathfinder-vX.Y.Z...` for `cuda-pathfinder`. Builds that support the +pre-tag bootstrap should validate the resulting release tuple rather than +hard-code the expected alpha/development suffix, and should report the +effective `git describe` result for traceability. + # Pull requests Treat the canonical upstream repository as read-only by default. For normal