Release Automation Contract

This document defines the v0.4 release automation shape. It is a contract for maintainer tools and agents, not a promise that every command exists yet.

Goals

The release process should be boring to execute and hard to publish accidentally.

Maintainers decide when to create candidates, approve irreversible actions, and accept known issues.
Tools run checks, build or collect artifacts, compute checksums, create reports, and call publication APIs after approval.
Agents follow the same machine-readable state as humans, ask for approval at gates, and avoid reconstructing release state from conversation.
Physical-machine validation uses near-final artifacts, not an arbitrary development checkout.
Every release candidate has an evidence bundle that can explain what was tested, where, and with which artifacts.

Phases

Candidate

release-candidate creates a local release state directory for one version. It may run local preflight checks, create the source bundle, collect wheel metadata from dist/, and write the first release-state.json.

Candidate creation must not tag, upload, publish, push, or mutate a GitHub release.

Machine Validation

Each validation host installs the candidate artifacts into a clean environment and runs a selected profile. The validator writes an evidence bundle with environment metadata, command results, captures, logs, skips, and failures.

The required v0.4 validation hosts are listed in VALIDATION_MATRIX.md. A missing host is recorded as missing evidence, not silently treated as support.

Report

release-report merges local state and machine evidence into a maintainer-facing summary. The report should show artifact identity, command outcomes, platform coverage, visual/capture differences, known skips, and remaining approval gates.

Rehearsal

TestPyPI and draft GitHub releases are rehearsals. They require explicit approval, but they are not the final publication gate. Rehearsal commands may upload to TestPyPI or create a GitHub draft release only after the candidate evidence is coherent.

Publication

Publication commands execute maintainer-approved irreversible actions:

create or push the final tag;
upload to PyPI;
publish the GitHub release;
publish documentation;
publish announcements.

Each irreversible class of action must require an explicit approval argument, normally yes, and must refuse if artifact checksums or release identity changed after validation.

Approval Gates

Agents and commands may proceed without maintainer approval for:

read-only inspection;
local preflight checks;
local candidate artifact creation;
local report generation;
dry-run publication planning.

Agents and commands must ask for approval before:

changing release versions;
creating tags;
pushing commits, tags, or branches;
uploading to TestPyPI, PyPI, or another package registry;
creating or publishing GitHub releases;
publishing documentation;
updating data submodule pointers;
staging generated/runtime binary payloads or vendored runtime libraries;
accepting a failed required machine as a known release exclusion.

Command Surface

The intended maintainer command surface is:

just release-plan 0.4.0rc1
just release-dry-run 0.4.0rc1 --wheel path/to/wheel.whl
just release-candidate 0.4.0rc1
just release-notes 0.4.0rc1
just release-docs-validate 0.4.0rc1
just release-validation-pack 0.4.0rc1 --wheel path/to/wheel.whl
just release-machine-plan 0.4.0rc1 --wheel path/to/wheel.whl
just release-machine-validate 0.4.0rc1
just release-ingest-evidence path/to/evidence.tar.zst
just release-report 0.4.0rc1 --strict-matrix
just release-gates 0.4.0rc1 --write-artifacts --strict-matrix
just release-testpypi 0.4.0rc1 --dry-run --dist-dir dist
just release-testpypi 0.4.0rc1 --dist-dir dist --confirm yes
just release-github-draft 0.4.0rc1 --dry-run
just release-github-draft 0.4.0rc1 --confirm yes
just release-create-tag 0.4.0 --dry-run
just release-create-tag 0.4.0 --confirm yes
just release-pypi 0.4.0 --dry-run
just release-pypi 0.4.0 --confirm yes
just release-github-publish 0.4.0 --dry-run
just release-github-publish 0.4.0 --confirm yes
just release-docs-publish 0.4.0 --dry-run

release-dry-run is the agent-friendly front door: it chains the local plan, candidate dry-run, release-notes preview, documentation validation dry-run, validation-pack rehearsal when wheels are supplied, strict matrix reporting when state exists, and all publication dry-runs without tagging, uploading, publishing, or pushing. release-notes writes build/release/<version>/release-notes.md, records it as the release-notes artifact, and leaves final wording to maintainer review. release-docs-validate records API reference checks and selected fenced snippet doctests as release evidence. release-machine-plan prints required physical-machine actions, current evidence status, and next ingest/report/gate commands. release-plan, release-candidate, release-validation-pack, release-machine-validate, and release-report cover the lower-level local automation slices. Publication commands stay explicit approval-gated operations.

Agent Behavior

An agent running the release process should:

read this contract, ARTIFACT_EVIDENCE.md, and VALIDATION_MATRIX.md;
run just release-dry-run <version> before mutating local release state;
run candidate/report commands and summarize failures in plain language;
give the maintainer exact per-machine validation commands;
ask for approval at every approval gate;
never tag, push, upload, publish, or approve known exclusions from inference alone.

Publication Safety

Publication commands must check:

version identity across package metadata, release notes, tag, and artifacts;
current commit matches the candidate state;
artifact checksums match the candidate evidence;
required validation evidence is present or explicitly waived;
git diff --check passes;
git status --short has no unreviewed staged surprises;
no unapproved data gitlink update is staged;
no unapproved generated/runtime binary payload is staged.

Final PyPI and GitHub publication should be separate commands. A single unattended command must not build, validate, tag, upload, and publish the final release.

6.3 KiB Raw Blame History