Skip to content

Version Policy

ZapTrace uses one explicit release line across Python metadata, runtime reporting, REST/MCP surfaces, the Rust extension, lockfiles, tags, and release evidence. pyproject.toml is the authoritative version source. Other surfaces are derived from it or checked deterministically in CI.

Active release-preparation identity

The prepared final identity is:

Surface Version
Python package, CLI, REST API, MCP server 0.3.1
Rust crate and Cargo lock package 0.3.1
Intended final tag v0.3.1
Latest published baseline v0.3.0
Distribution state release-preparation

This tree is not published evidence until the exact commit is tagged as v0.3.1 and the tagged-release workflow succeeds. Preparation reports remain mode=snapshot, published=false; the tag workflow re-verifies the same release identity and emits mode=release, published=true.

Lifecycle transitions

ZapTrace distinguishes development, release preparation, and tagged publication:

  1. Development: Python 0.3.1.dev0; Cargo 0.3.1-dev.0. Branch and pull-request evidence is unreleased snapshot evidence.
  2. Release preparation: a repository-owned branch named exactly release/v<version> may carry an RC or final package identity before its tag exists. Quality records this as release-preparation with published=false; development versions, mismatched branch names, and already-used release tags are rejected.
  3. Release candidate: Python 0.3.1rc1; Cargo 0.3.1-rc.1; annotated tag v0.3.1rc1. The report state is tagged-release-candidate.
  4. Final release: Python and Cargo 0.3.1; annotated tag v0.3.1. The report state is tagged-final-release.

Immediately after a final release is cut, main receives a post-release bump to the next patch's .dev0 line. For example, after v0.3.1, development advances to Python 0.3.2.dev0 and Cargo 0.3.2-dev.0 before unrelated changes are merged.

Synchronization rules

scripts/ci_version_consistency.py checks:

  • pyproject.toml and the root zaptrace package entry in uv.lock;
  • zaptrace_core/Cargo.toml and the root zaptrace-core entry in Cargo.lock;
  • runtime zaptrace.__version__;
  • REST API_VERSION and MCP SERVER_VERSION;
  • Python PEP 440 to Cargo SemVer mapping;
  • development trees use .devN and do not reuse an already released final line;
  • release refs exactly match v<package-version>;
  • release tags resolve to the exact checked-out source commit;
  • future release tags are annotated Git tag objects.

The Quality workflow publishes version-consistency.json and version-consistency.md. The tag workflow publishes version-consistency-release.json and version-consistency-release.md. Both reports embed the shared evidence identity.

Tag trust policy

Future release tags must be annotated. The historical v0.3.0 lightweight tag is retained as a grandfathered historical record; it is not the template for future releases.

The repository records that cryptographic tag verification is not currently required because the repository does not yet contain a reviewed maintainer trust root and key-rotation policy. The machine-readable policy records this as require_cryptographic_tag_verification=false; reports must not imply a verified signature. Enabling signature enforcement requires a separate reviewed change that documents trusted identities, key rotation, revocation, and CI verification behavior.

Release preparation

A release PR must use the exact release/v<version> branch name, synchronize all version surfaces, and change the package stage deliberately. Quality evaluates that PR with the bounded release-preparation context while all ordinary pull requests remain in development context. The resulting non-development identity is also accepted for the single main push transition before tagging; scheduled/manual main validation remains development-only, so a final identity cannot remain parked on main. The release tag is created only after the release PR is merged; the tag workflow then re-verifies the exact tagged commit in release context. The tag workflow rejects:

  • a development version;
  • a tag/package mismatch;
  • a lightweight future tag;
  • a tag pointing to a different commit;
  • Python, runtime, API/MCP, Rust, or lockfile disagreement.

Local verification

.venv/bin/python scripts/ci_version_consistency.py \
  --context development \
  --source-ref "$(git symbolic-ref -q HEAD || echo detached)" \
  --source-commit "$(git rev-parse HEAD)" \
  --output version-consistency.json \
  --markdown version-consistency.md \
  --strict

A passing version report proves identity consistency only. It does not prove functionality, security, package correctness, fabrication readiness, or release quality.