Releasing workspace packages¶
The root .github/workflows/release.yml builds one package per candidate.
contracts-vX.Y.Z selects robotics-runtime-contracts; harness-vX.Y.Z selects
robotics-acceptance-harness. An RC tag uses -rc.N, for example
contracts-vX.Y.Z-rc.1, corresponding to package version X.Y.Zrc1.
The selected package’s committed pyproject.toml version must match exactly.
Tag pushes must resolve to the checked-out commit and be reachable from origin/main.
Compatibility and consumer scope¶
Review a candidate against the released package and its documented public interfaces, not just the version currently written in the source tree. The architecture identifies these boundaries. Accessible private modules and internal implementation choices are not additional stable APIs.
The packages use pre-1.0 versions. Following the distinctions in Semantic Versioning, choose the version for the complete candidate: a patch contains compatible corrections; new public functionality, deprecations or intentional incompatible migrations use a new minor line before 1.0. Describe the supported scope and migration in the package changelog and references. This is not an unconditional stability or fixed-duration support promise.
Before removing a documented interface, audit its callers, package exports, resources, build scripts and consumer checks. Announce its replacement or retirement in a separately versioned release. Keep previously released artifacts, schema identities and signed archive references unchanged; historical consumers retain their pinned tools. The existing schema compatibility gate and installed-consumer checks must validate the candidate’s declared scope.
A package release, a consumer cohort change and native execution admission are separate decisions. A new dependency range does not update an existing lock or qualify an image. Adopt exact published artifacts in each consumer only after its checks pass; do not silently replace released MCP bundles or archive bindings. The harness prerequisite below still requires the exact released contracts sources and metadata. Package publication does not waive the execution profile’s supplier, platform or lifecycle gates.
Candidate checks¶
Released packages are listed on the contracts project and harness project. The committed contracts manifest and harness manifest select the candidate versions. The harness changelog names its exact contracts release prerequisite; the preflight verifies that release and the corresponding package sources.
A candidate dry run builds the selected package’s wheel and source archive, then verifies their isolated installation. Publication requires separate publisher registration; infra images and native execution profiles have their own qualification gates.
workflow_dispatch requires a candidate input and always runs in dry-run mode.
Select the ref containing the reviewed source and matching version. It executes helper
tests, preflight, wheel/sdist builds and isolated installs, then uploads verification
evidence and distributions. Both publication jobs are skipped, including OIDC issuance,
PyPI publishing, GitHub release creation and attestations. There is no publish input.
The workflow must first exist on the default branch for GitHub’s manual-run interface.
The same build checks can run locally from the root in a separate tools environment
(POSIX shell example; on Windows use the environment’s Scripts/python.exe):
export UV_PROJECT_ENVIRONMENT="$PWD/artifacts/release-tools"
uv sync --locked --only-group dev --no-install-workspace --python 3.12
PY="$UV_PROJECT_ENVIRONMENT/bin/python"
"$PY" -m pytest tests/release
candidate="$("$PY" - <<'PY'
import tomllib
with open("packages/contracts/pyproject.toml", "rb") as source:
print("contracts-v" + tomllib.load(source)["project"]["version"])
PY
)"
"$PY" -m scripts.release.plan \
--candidate "$candidate" --event workflow_dispatch \
--repository mmkolpakov/robotics-runtime --output artifacts/release/plan.json
uv build --package robotics-runtime-contracts --no-sources --out-dir artifacts/release/dist
"$PY" -m scripts.release.verify_install \
--plan artifacts/release/plan.json --dist artifacts/release/dist \
--repository mmkolpakov/robotics-runtime \
--python 3.12 --report artifacts/release/clean-install.json
Use a fresh distribution directory for each candidate. Its only distribution files must
be one wheel and one sdist; the .gitignore marker created by uv is allowed. The helpers
do not create tags or releases. A harness preflight also needs fetched workspace tags and
read access through gh to the root repository’s releases.
Contracts must be released before harness¶
The harness preflight derives the contracts tag from the actual contracts package version in this checkout. It never selects a lexically sorted or arbitrary latest tag. It requires all of the following, even in dry-run mode:
Exactly one unconditional, index-based contracts dependency with the selected minor’s lower bound and exclusive next-minor upper bound. The dependency must match the selected stable contracts minor line.
The exact root tag
contracts-vX.Y.Z, with a published, stable, non-draft GitHub release inmmkolpakov/robotics-runtime. Importedcontracts-legacy/*tags do not satisfy this.An identical Git tree for
packages/contracts/srcand an identical[project]table inpackages/contracts/pyproject.tomlat that tag and at the candidate commit. A change to the contracts sources or project metadata after its release blocks harness until contracts is versioned and released again. Repository-only files such as contributor documents, tests and the build requirement may change in between.A
packages/harness/CHANGELOG.mdsection for the harness version naming that exact contracts tag. Maintainers should link it to the root repository’s corresponding release.Successful isolated installation of the exact contracts version from PyPI, with its installed source and schema files matching the verified checkout byte for byte.
Each harness candidate requires the exact contracts tag to have completed publication on both PyPI and GitHub. Local builds alone do not establish release readiness.
The plan records both commits and package tree IDs, the contracts requirement and source file SHA-256 digests. The clean-install check binds PyPI’s contracts code and resources to that plan. Merely finding a similarly named tag or an installable version is insufficient.
Build and installation boundary¶
The build uses uv build --package <name> --no-sources, as recommended by
uv’s packaging guide.
Wheel and sdist metadata must agree with their filenames, the candidate and the expected
dependency bounds. Direct URL, local path and VCS dependencies are rejected.
Each archive is copied to its own temporary directory outside the workspace and installed
into a new venv. The installer disables uv configuration and workspace sources, clears
Python/index environment overrides, and uses only PyPI plus the copied selected archives.
The sdist is actually built and installed there. Harness release installs include the
authenticated wheel of the selected released contracts version. uv pip check verifies
dependency compatibility.
Smoke runs use the clean interpreter with -I, without PYTHONPATH or editable packages.
They check installed file inventories and digests, schema resource loading, API validation
of the copied consumer example, runtime writer round-trip, structured qualification
diagnostics, the new role resources, and robotics-contracts validate. Harness additionally
checks its existing EvaluationContext/ProductEvaluator exports and
robotics-acceptance explain. Contracts has no --version option. These checks
exercise the existing public API; they do not establish a general consumer SDK.
A temporary directory configured inside the workspace fails.
Harness verification also authenticates the exact selected contracts wheel with stock GitHub release and source/workflow attestation checks, and requires the published PyPI bytes to have the same SHA-256. The existing tag, source and project-metadata comparison still applies. A missing release or failed verifier blocks publication; a locally built candidate is not a published prerequisite.
Candidate-pair consumer checks exercise both harness archives with the matching source-built contracts wheel. The original published pair remains a separate baseline, and the stock resolver must reject its unsupported contracts version for the new candidate. Harness release checks run the same foreign Node fixture with the authenticated published contracts wheel before publication. This test fixture uses Docker in CI; offline built-in assessment does not require it, and these checks do not qualify an OCI execution profile.
External publication settings¶
Repository code cannot complete or attest to the following account settings. A maintainer must verify them before enabling publication:
Register a GitHub Trusted Publisher separately for both PyPI projects, with owner
mmkolpakov, repositoryrobotics-runtime, workflow filenamerelease.yml, and environmentpypifor contracts andpypi-harnessfor harness. Pending publishers for two new projects cannot share the same repository/workflow/environment tuple. Follow PyPI’s publisher registration guide, or configure a pending publisher if the project does not exist yet. Registration itself does not establish that a version is available from PyPI. Do not add a long-lived PyPI API token to this workflow.Create the GitHub
pypiandpypi-harnessenvironments, each with required reviewers. Permit onlycontracts-v*tags inpypiandharness-v*tags inpypi-harness. Check required branch/tag protection independently; this workflow does not change rules or the stablevalidateCI context.Enable immutable GitHub releases. The final job deliberately fails if
gh release verifyorgh release verify-assetcannot verify the released tag and downloaded asset bytes.Set repository variable
PYPI_PUBLISH_ENABLEDto exactlytrueonly after publisher registration and release prerequisites are verified. Without it, tag builds run but publication jobs are skipped. A green build alone does not mean anything was published.
All actions are pinned to full commit SHAs. The build job has contents: read and
attestations: read; the PyPI job uses the environment selected by the validated release
plan with id-token: write.
There is no user-supplied environment input. The separate GitHub release
job has the contents, attestation and OIDC permissions it needs, and runs only after PyPI
succeeds. Failed, cancelled or skipped prerequisites cannot publish a GitHub release.
Both jobs consume the exact uploaded distributions; neither rebuilds them.
PyPI Trusted Publishing emits its publish attestations. The GitHub job creates build
provenance using actions/attest. Consumers must verify the workflow identity
https://github.com/mmkolpakov/robotics-runtime/.github/workflows/release.yml@refs/tags/<tag>;
historical archives retain their original producer identity. Old package publishers
and repositories are not removed or archived by this workflow.
Publishing does not use skip-existing, overwrite assets, or move tags. If PyPI succeeds
and the GitHub job fails, inspect the failed job and retained artifacts and rerun only that
failed job after resolving the cause. A full rerun can fail on PyPI’s existing files; do not
hide that conflict or substitute rebuilt bytes. Retained workflow evidence expires after
seven days; maintainers must preserve it when investigating a partial publication.
Compiled host¶
.github/workflows/host-release.yml builds a TGZ with private: true and ordinary
npm dependency installation. PR and manual runs verify a clean rebuild, archive
identity and installation outside the source workspace; they do not publish or
qualify native execution.
The release manifest records package_lock_sha256, the SHA-256 of the single
workspace root package-lock.json; the TypeScript packages no longer keep
separate lockfiles. A candidate whose host/package.json version already
names an existing host-v* tag must keep the packed host content identical
to that tag, or the build refuses before packing and the version must be
bumped. The MCP CI job retains the same packed host TGZ beside the offline
bundle in artifacts/mcpb and covers both with SHA256SUMS.
Before publication, verify the repository’s current release-immutability setting,
the host/provider source cohort, cancellation and retained verification after
source deletion. Set HOST_QUALIFIED_SOURCE_SHA and HOST_QUALIFIED_ASSET_SHA256
to that accepted cohort. The build must match its source tree and archive bytes;
the original source identity stays separate from the tag/build commit. Enable
HOST_RELEASE_PUBLISH_ENABLED=true and create a unique main-reachable
host-v<host/package.json version> tag. PyPI environments remain separate.
The immutability settings API requires Administration read; an unauthorized
response does not establish whether the setting is enabled.
The workflow stages a draft with five assets. Immediately before publishing,
repeat check_draft_assets and check_live_tag using the archived run inputs:
download the exact remote asset set, compare every byte, and verify the peeled
live tag against the build manifest and tag-trigger SHA. Reject partial, stale
or surplus drafts without replacing their assets. Publish the accepted draft
with gh release edit <tag> --draft=false.
For a published release, require isImmutable, verify it with
gh release verify --format json, recheck the exact live commit and verify every
asset. Never move an existing tag or replace published bytes. Native provider,
hardware and cloud qualification require their own independent consumer gates.