Skip to content

Commit 36e4d40

Browse files
authored
Add "Git-derived version lifecycle" section in AGENTS.md (#2932)
1 parent 09569cd commit 36e4d40

1 file changed

Lines changed: 32 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,38 @@ guide for package-specific conventions and workflows.
1212
- `cuda_core/`: High-level Pythonic CUDA APIs built on top of bindings.
1313
- `cuda_python/`: Metapackage and docs aggregation.
1414

15+
# Git-derived version lifecycle
16+
17+
Package versions are derived from reachable Git tags by `setuptools-scm`.
18+
Allow its standard tag parsing and version progression to govern versions; do
19+
not add custom tag parsing or manufacture a version when an appropriate tag is
20+
already reachable from the commit being built.
21+
22+
For each package tag namespace and target release `X.Y.Z`:
23+
24+
- Reserve `aN` (alpha) tags for internal purposes. Do not use them as public
25+
release milestones.
26+
- Before the first retained tag for a new version line exists, an internal
27+
preview build may create a local, lightweight `X.Y.Za0.dev0` tag at a
28+
validated ancestor. The synthetic tag must remain local to the build and
29+
must never be pushed.
30+
- Use `X.Y.Za0` for the first retained internal milestone. Untagged descendants
31+
then naturally become `X.Y.Za1.devN` under the standard `setuptools-scm`
32+
version scheme. A later exact `aN` milestone requires an explicit decision;
33+
do not create a tag for every pull request or build.
34+
- When any tag for `X.Y.Z` in the package's namespace is reachable, do not
35+
create a synthetic tag. Let `setuptools-scm` derive the version from the
36+
existing history.
37+
- Treat pushed tags as immutable. Correct an unsuitable tagged state with a
38+
new versioned milestone rather than moving or replacing the existing tag.
39+
40+
Use the package's established tag namespace, such as `vX.Y.Z...` for
41+
`cuda-bindings` and `cuda-python`, `cuda-core-vX.Y.Z...` for `cuda-core`, and
42+
`cuda-pathfinder-vX.Y.Z...` for `cuda-pathfinder`. Builds that support the
43+
pre-tag bootstrap should validate the resulting release tuple rather than
44+
hard-code the expected alpha/development suffix, and should report the
45+
effective `git describe` result for traceability.
46+
1547
# Pull requests
1648

1749
Treat the canonical upstream repository as read-only by default. For normal

0 commit comments

Comments
 (0)