Skip to content

Product version and release tags

One product version authority

The root VERSION file is the only source-of-truth value for the product release. Its format is YY.MM.VV (for example 26.10.4 or 26.10.5). Do not edit .ai/VERSION, .ai/runtime/VERSION, generated documentation or active catalogue versions individually.

From the repository root, prepare a new version with:

# 1. Edit exactly one file: VERSION (for example to 26.10.5)
python3 scripts/versioning.py sync
python3 scripts/versioning.py check

sync is repeatable and updates only allowlisted product projections:

  • the two installation-version copies under .ai/;
  • roles.json and workflows.json current product-version fields;
  • the generated release manifest, validation page and inventory sections of both READMEs;
  • the installed CLI GUIDE, which is a generated copy of its canonical Markdown source.

The MkDocs source uses 26.10.5 only for current product identity. The MkDocs hook inserts the root VERSION into the rendered site. Nothing edits published HTML after building it.

Independent versions and immutable history

Release version is not a schema version, JAI core version, Artifact Contract version, migration target, historical dataset version or evidence timestamp. For example:

  • ArtifactContract-v3 and schema/contracts/artifact-v3.schema.json stay stable while their contract remains unchanged;
  • historical schema/26.10.4/ files, schema registry migration paths and previous 26.10.x target IDs remain unchanged;
  • changelogs, historical release pages, approval/audit records and earlier qualification results are preserved;
  • SBOM.spdx.json, PROVENANCE.json, QUALIFICATION-A-H.json and ZIP checksum are re-generated by CI for each actual release, not rewritten by sync.

Some domain registries still contain a top-level release field that identifies the baseline in which that particular model or mapping originated. Those are provenance/compatibility facts, not a second current-product version. Their contents change only when the corresponding contract or domain model changes.

Publishing with no manual release approval

After editing VERSION, running sync, and committing/pushing the synchronized source on main:

# Example; substitute the number currently written in VERSION.
git tag -a 'release@26.10.5' -m 'JAI 26.10.5'
git push origin 'release@26.10.5'

GitHub Actions rejects a tag if its version differs from the VERSION committed in the tagged revision. It validates the synchronized files, runs the A–H gates, builds the ZIP/metadata, and publishes the production GitHub Release automatically when the checks pass. No draft, external signing, or human approval is required for the release itself.

Do not move a published tag. Release changes under a new version. New release functionality and changes still need a human-authored changelog entry; the version synchronization tool cannot invent factual release notes.

Diagnostics

python3 scripts/versioning.py check --root .
python3 scripts/versioning.py check --root . --tag 'release@26.10.5'
python3 .ai/runtime/tools/generate_docs.py --check --root .

If the source VERSION was changed but sync was skipped, version checks intentionally fail and report which projection is stale. Avoid any global sed, perl or file-wide replacement of release numbers.