This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Versioning

Global repository and project versioning

versioning owns versions for this repository and its first-party projects. It deliberately does not manage versions of third-party dependencies.

The repository uses SemVer-compatible calendar versions:

  • ordinary development: 0.0.0-dev;
  • nightly trunk tag: vYYYY.W.0-nightly.YYYYMMDD;
  • weekly release branch: releases/YYYY.W;
  • release tag: vYYYY.W.PATCH.

YYYY and W are the ISO week-year and week. The week is not zero-padded, because SemVer forbids leading zeroes in numeric identifiers. Patch zero is the release branch point. Every first-parent commit after that point advances the calculated patch number by one.

Calculated versions and Bazel status omit the Git tag’s leading v.

A commit may carry one nightly tag and one release tag when a nightly is promoted. Branch context selects the channel automatically. On detached HEAD, pass --channel release or --channel nightly for that exact co-tagged commit. For an untagged detached commit from a release branch, pass --release YYYY.W so the tool can calculate its patch from the correct branch-point tag.

Build and inspect the tool with:

bazel_agent bazel run //tools/versioning/cmd/versioning -- show

For a stamped build, use the bootstrap entry point. It generates a source-current Bazel launcher under out/versioning/, then the Go tool runs Bazel with itself as workspace status:

tools/versioning/cmd/versioning/versioning.sh bazel -- \
  build --config=release //path/to:artifact

Read $versioning for the guarded nightly, release, and Bazel stamping workflows.

versioning also owns a typed, reviewed release-ref plan and a provider-neutral guarded publisher for the generated nightly and release tags. It never merges versioning, delivery, or goal authority; the tool retains its own release-refs authority.

Generate a deterministic plan from the resolved version state:

bazel_agent bazel run //tools/versioning/cmd/versioning -- release-plan \
  --plan out/delivery/release-plan.json

The plan records the exact version, channel, commit, tree state, target refs (tag-only for nightly, branch-plus-tag for release), the expected remote preconditions, and whether atomic multi-ref publication is required. It is reviewed before consumption and is not an authorization.

Publish the reviewed plan only after explicit release scope:

bazel_agent bazel run //tools/versioning/cmd/versioning -- release-publish \
  --plan out/delivery/release-plan.json \
  --receipt out/delivery/release-ref-receipt.json

The guarded publisher fetches expected remote state, acquires a distinct release-refs lease, publishes the refs (atomically when required and supported), and verifies the remote before emitting a ReleaseRefReceipt. An existing immutable release tag never moves; a remote that cannot guarantee atomic multi-ref publication is an explicit refusal, never a generic success.