Releases
main carries X.Y.Z-dev, which nothing may pin. A pilot is a frozen, tagged X.Y.Z-pilot.N; a full release is a frozen, tagged X.Y.Z promoted from a pilot (ADR-0013).
Cut a pilot
From a clean, up-to-date main, say what changed and which project or finding asked for it:
python3 tooling/cut_release.py pilot 0.1.0 --note "First pre-release, for a novaOS prototype to pin"
tooling/gate-at-commit.sh <cut-commit>
python3 tooling/cut_release.py tag
python3 tooling/cut_release.py dev 0.1.0pilot picks the next pilot number, stamps the version into the ontology, the catalog’s current distribution and the release manifest, lists the fixture ledger (tests/fixtures/ledger/), writes a sha256 for every artifact, adds the pilot to the changelog and commits. It prints the commit and the release digest, the sha256 of the manifest. gate-at-commit.sh runs check-standard.sh on that commit in a detached worktree. tag refuses until the gate has passed on exactly that commit. dev commits the return to X.Y.Z-dev.
main takes changes only through pull requests, so pilot commits to a new branch release-<version> (here release-0.1.0-pilot.1), and tag and dev refuse to run anywhere else. Push the branch with its tag (--follow-tags), open a pull request into main and merge it with Create a merge commit. Squash or rebase would rewrite the cut commit, and main would no longer hold the tagged commit.
Promote a pilot
Only the standard author promotes, after a project has used the pilot and its findings are resolved or deferred. A promotion changes version strings only: it is refused if anything else changed since the pilot. It also starts on main, commits to release-<version> (here release-0.1.0) and is merged the same way.
python3 tooling/cut_release.py promote 0.1.0-pilot.N
tooling/gate-at-commit.sh <cut-commit>
python3 tooling/cut_release.py tag
python3 tooling/cut_release.py dev 0.2.0The dev after a promotion opens dataRequirements/releases/0.2.0/ and a catalog distribution for 0.2.0-dev.
What a project pins
Two values together: the version (0.1.0-pilot.1, from the tag v0.1.0-pilot.1) and the release digest (sha256:…, printed at the cut). Never pin a -dev version, a branch or a working tree. Fetch the tag’s files into a directory laid out as in the repository, for example git archive v0.1.0-pilot.1 | tar -x -C release/, then check them:
python3 tooling/verify_release.py 0.1.0-pilot.1 sha256:<digest> release/Exit 0 means it is the release pinned; 1 prints one line per problem (a code, the path, a message); 2 is a usage error. Stop on anything but 0. The digest is the manifest’s, not an archive’s: an archive of the tag is checked by unpacking it and running this check.