Skip to content

Clarify release version policy #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ip332 merged 1 commit into from
Sep 18, 2026
Merged

Clarify release version policy #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/release-artifacts.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,9 @@ jobs:
cmake -S source-tree -B source-tree/build -DCMAKE_BUILD_TYPE=Debug
cmake --build source-tree/build --parallel
cmake --install source-tree/build --prefix "$PWD/source-prefix"
# A normal Git checkout may have a commit-count development version;
# the reconstructed release archive must report the explicit tag's
# numeric release version from its injected fallback metadata.
expected="${RELEASE_TAG#v}"
expected="${expected%-rc.*}"
test "$(source-tree/build/tools/quarry-schema-compiler --version | sed 's/^quarry-schema-compiler //; s/ .*//')" = "$expected"
Expand Down
42 changes: 24 additions & 18 deletions docs/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,14 @@ Revision = commits after the last commit that changed git_version
The commit that introduces or changes `git_version` is revision `0`. The next
commit is revision `1`, and changing `0.1` to `0.2` starts `0.2.0`.

The CMake resolver in `cmake/QuarryVersion.cmake` is authoritative. It exposes
the numeric version to the CMake package, compiler, translator, and generated
version header. The human-readable CLI display appends `-dirty` when tracked
files differ from `HEAD`; untracked files are intentionally ignored. Numeric
package versions never contain the dirty suffix.
The CMake resolver in `cmake/QuarryVersion.cmake` is authoritative for a normal
Git checkout. It exposes the numeric development version to the CMake package,
compiler, translator, and generated version header. This means that a current
development checkout can legitimately report a version such as `0.1.262`; it
does not need to numerically match a future release tag. The human-readable CLI
display appends `-dirty` when tracked files differ from `HEAD`; untracked files
are intentionally ignored. Numeric package versions never contain the dirty
suffix.

Complete Git history is required. Shallow checkouts fail clearly and should be
repaired with:
Expand All @@ -26,19 +29,22 @@ repaired with:
git fetch --unshallow
```

For a source archive without `.git`, the tracked
`cmake/QuarryResolvedVersion.cmake` template receives the release tag and Git
identity through Git's `export-subst` archive mechanism. A release tag such as
`vX.Y.Z-rc.N` supplies the numeric `X.Y.Z` fallback; the tag's Major.Minor must
match `git_version`. The same file is also generated beside normal build
artifacts for packaging. These fallbacks are used only when full Git history is
unavailable. Ordinary Git builds do not use them and cannot silently fall back
to an unknown version. An untagged or malformed archive fails with a clear
diagnostic.

Release tags must point to a clean commit whose numeric version matches the
tag's numeric portion, for example `vX.Y.Z-rc.N` for resolved version `X.Y.Z`.
Release creation must reject tracked modifications.
For a source archive without `.git`, the release tooling writes the explicit
release identity and Git identity into
`cmake/QuarryResolvedVersion.cmake`. A release tag such as `vX.Y.Z-rc.N`
therefore supplies the numeric `X.Y.Z` version to the reconstructed archive,
wheel, and sdist. Release candidates intentionally retain the numeric package
version `X.Y.Z`; the `-rc.N` suffix identifies the release tag and is not part
of the numeric package version.

Release tags identify release artifacts; they are not required to match the
commit-count version of the tagged development checkout. Release creation must
still use a clean tracked commit, and the tag's major/minor must match
`git_version`. Release verification must confirm that reconstructed archives
and packaged artifacts report the numeric version derived from the explicit
release tag. Ordinary Git builds do not use archive fallback metadata and
cannot silently fall back to an unknown version. An untagged or malformed
archive fails with a clear diagnostic.

Release versioning is independent from compatibility contracts: C++ generated
code epoch `3`, C generated code epoch `2`, Python generated code epoch `1`,
Expand Down
Loading