Skip to content

livery.workshop._release_driver

livery.workshop._release_driver

workflow.release: the release train's driver on the engine.

One release shape for a set of N >= 1 packages: derive each member's version from its commits and its entry through the release notes' provider, bump floors within the set only, stamp, commit per member in dependency order, and hand the branch to the shared engine. The branch decides the act: main-family (main and the engine's workflow/ namespace) runs the real train, any other branch is the dev act, a wheel straight from the branch. --local is everything that stays on this machine: derive, build, validate, report, then roll the stamps back like a failed prepare, leaving dist/ and the report.

Classes:

Name Description
MemberPlan

One member's derived release: the package and its next version.

ReleaseDriver

The release kind's driver for the shared engine.

Functions:

Name Description
release_name

The workflow name a set earns: its directories, sorted and +-joined.

resolve_set

The named packages, in dependency order; every name must exist.

derive_plans

Each member's next version, every member refused when unchanged.

member_pairs_at

(distribution, version) for each member in the member list at ref.

bump_set_floors

Raise floors between co-released members through the stamp phase; the files.

rollback_prepare

Restore exactly the files prepare writes; never raises.

verify_set

Run the publish job's own checks over the stamped set, before any leg.

proved_resolutions

The resolutions package's release tests at, and the file that listed them.

validate_member

Run the member's test phase isolated once per resolution it proves; report each.

require_verified_base

Wait for the base's own push CI to be green; stop on red or skip.

release_title

The release pull request's title: each member with its version, or a count.

runs_the_train

Whether workflow.release on branch is the release train, not the dev act.

fresh_receipts

Fetch origin's tags, so a derivation reads every receipt a wave cut.

local_release

Everything that stays on this machine, then the stamps roll back.

await_wave

The id of the newest wave run not in before, or None when none appears.

dispatch_flow

Dispatch the wave for a merged, unpublished release, or say why not.

newest_release_squash

The newest release squash on the base, as (sha, subject); ("", "") when none.

pending_release_waves

Every recent release squash whose receipts are not all cut, oldest first.

pending_release_wave

The oldest release squash with an uncut receipt, or None.

pending_release_wave_for

The oldest uncut squash whose receipts touch members, or None.

uncut_in_set

The uncut receipts, packages/<member>/v<x>, that belong to members.

workflow_release

Release a set of packages: the branch decides the act.

run_release

Drive a release through the engine; an armed one re-derives a stale set.

set_moved

Whether release name's open pull request is stale in its set's paths.

workflow_release_dispatch

Dispatch the release wave for a merged, unpublished release; green otherwise.

workflow_release_check_title

Verify a release PR's title against the release's member list.

workflow_release_check_fresh

Refuse a release pull request whose base moved in its set's paths.

workflow_release_publish

Publish the squash at --ref: the wave, receipts cut per member.

collected_wheels

Whether the run collected what a job built for this wave, judged inside CI alone.

Attributes:

Name Type Description
BASE_TIMEOUT
BASE_POLL
SILENT_NUDGE_AFTER
NAME_LIMIT
PROVE
RESOLUTIONS
DEFAULT_RESOLUTIONS
TITLE_LIMIT
RELEASE_WORKFLOW
release_group
REDERIVE_LIMIT

BASE_TIMEOUT module-attribute

BASE_TIMEOUT = 30 * 60

BASE_POLL module-attribute

BASE_POLL = 15

SILENT_NUDGE_AFTER module-attribute

SILENT_NUDGE_AFTER = 3 * 60

NAME_LIMIT module-attribute

NAME_LIMIT = 64

PROVE module-attribute

PROVE = 'prove'

RESOLUTIONS module-attribute

RESOLUTIONS = ('floor', 'latest', 'head')

DEFAULT_RESOLUTIONS module-attribute

DEFAULT_RESOLUTIONS = ('floor', 'latest')

TITLE_LIMIT module-attribute

TITLE_LIMIT = 80

RELEASE_WORKFLOW module-attribute

RELEASE_WORKFLOW = 'release.yml'

release_group module-attribute

release_group = workflow.group('release', help='The release train')

REDERIVE_LIMIT module-attribute

REDERIVE_LIMIT = 3

MemberPlan dataclass

MemberPlan(package: Package, version: str)

One member's derived release: the package and its next version.

Attributes:

Name Type Description
package Package
version str

package instance-attribute

package: Package

version instance-attribute

version: str

ReleaseDriver

ReleaseDriver(root: Path, repo: Repository, members: tuple[Package, ...], *, armed: bool, force_unverified_base: bool = False, wave_timeout: float = 1800.0)

The release kind's driver for the shared engine.

Methods:

Name Description
discard

Give up the prepared branch: the base moved in the set's paths.

legs_kept

The members whose legs from the discarded prepare still hold.

prepare

Derive, stamp, and commit the set; recover an existing branch.

on_merged

The merge point dispatches the wave; follow it to its verdict.

Attributes:

Name Type Description
kind
members
name
armed
watch
branch str
base str
Source code in packages/workshop/src/livery/workshop/_release_driver.py
def __init__(
    self,
    root: Path,
    repo: Repository,
    members: tuple[Package, ...],
    *,
    armed: bool,
    force_unverified_base: bool = False,
    wave_timeout: float = 1800.0,
) -> None:
    self._root = root
    self._repo = repo
    self._members = members
    self.members = tuple(p.member for p in members)
    self.name = release_name(self.members)
    self.armed = armed
    self._force = force_unverified_base
    self._wave_timeout = wave_timeout
    # An armed release follows its pull request for as long as it
    # would wait for the wave; the engine's own tests pass zero.
    self.watch = wave_timeout
    # Set by `discard`: the next prepare starts from the base, and
    # the given-up branch's manifest says which members' legs
    # still hold.
    self._fresh = False
    self._previous: tuple[str, tuple[tuple[str, str], ...]] | None = None

kind class-attribute instance-attribute

members instance-attribute

members = tuple(p.member for p in members)

name instance-attribute

name = release_name(self.members)

armed instance-attribute

armed = armed

watch instance-attribute

watch = wave_timeout

branch property

branch: str

base property

base: str

discard

discard() -> None

Give up the prepared branch: the base moved in the set's paths.

The next prepare derives the set again from the base and force-pushes the branch, so the open pull request carries the new stamps, entries and Mined-At. The given-up branch's manifest is kept: a member whose directory the base did not move since that prepare, at the same versions for the whole set, keeps its legs' verdict instead of running them again.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def discard(self) -> None:
    """Give up the prepared branch: the base moved in the set's paths.

    The next prepare derives the set again from the base and
    force-pushes the branch, so the open pull request carries the
    new stamps, entries and ``Mined-At``. The given-up branch's
    manifest is kept: a member whose directory the base did not
    move since that prepare, at the same versions for the whole
    set, keeps its legs' verdict instead of running them again.
    """
    import json

    from livery.workshop._publish import MANIFEST, read_manifest

    root = self._root
    git.fetch(root)
    text = git.file_at(root, f"origin/{self.branch}", MANIFEST)
    pairs = read_manifest(text) if text else None
    mined = ""
    if pairs:
        with contextlib.suppress(ValueError, TypeError, AttributeError):
            mined = str(json.loads(text).get("mined-at") or "")
    self._previous = (mined, pairs) if pairs and mined else None
    if git.current_branch(root) == self.branch:
        git.switch(root, self.base)
    if git.local_branch_exists(root, self.branch):
        git.delete_branch(root, self.branch)
    self._fresh = True

legs_kept

legs_kept(plans: tuple[MemberPlan, ...], mined_at: str) -> set[str]

The members whose legs from the discarded prepare still hold.

Only when the whole set keeps its versions (a co-member's new version moves the floors every other member is tested at), and then each member the base did not touch between the two mining points.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def legs_kept(self, plans: tuple[MemberPlan, ...], mined_at: str) -> set[str]:
    """The members whose legs from the discarded prepare still hold.

    Only when the whole set keeps its versions (a co-member's new
    version moves the floors every other member is tested at), and
    then each member the base did not touch between the two mining
    points.
    """
    if self._previous is None:
        return set()
    previous_mined, previous_pairs = self._previous
    now = tuple((plan.package.member, plan.version) for plan in plans)
    if tuple(sorted(previous_pairs)) != tuple(sorted(now)):
        return set()
    kept: set[str] = set()
    for plan in plans:
        try:
            moved = git.log_paths(
                self._root, f"{previous_mined}..{mined_at}", (plan.package.path,)
            )
        except git.GitError:
            continue  # an unreadable span proves nothing: run the legs
        if not moved:
            kept.add(plan.package.member)
    return kept

prepare

prepare() -> Submission | None

Derive, stamp, and commit the set; recover an existing branch.

A branch already alive locally or on the remote is recovery: nothing is rebuilt, the engine re-submits what the branch holds, and titles come from the ref, never the working tree.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def prepare(self) -> Submission | None:
    """Derive, stamp, and commit the set; recover an existing branch.

    A branch already alive locally or on the remote is recovery:
    nothing is rebuilt, the engine re-submits what the branch
    holds, and titles come from the ref, never the working tree.
    """
    root = self._root
    if not self._fresh and (
        git.local_branch_exists(root, self.branch)
        or self._repo.branch_exists(self.branch)
    ):
        if git.current_branch(root) != self.branch:
            if not git.local_branch_exists(root, self.branch):
                git.fetch(root)
                git.run(
                    root, "checkout", "-b", self.branch, f"origin/{self.branch}"
                )
            else:
                git.switch(root, self.branch)
        print(f"  recovering the prepared {self.name} from its branch")
        self._require_fresh_base()
        return self._submission_from_ref()

    require_verified_base(self._repo, root, self.base, force=self._force)
    plans = derive_plans(self._root, self._members)
    mined_at = git.head_sha(root)
    kept = self.legs_kept(plans, mined_at)
    git.create_branch(root, self.branch)
    prepared = False
    floor_changes: list[str] = []
    try:
        floor_changes = bump_set_floors(self._root, plans)
        if floor_changes:
            print(f"  floors raised within the set: {', '.join(floor_changes)}")
        _write_manifest(self._root, plans, mined_at=mined_at)
        for plan in plans:
            prepare_release(self._root, plan.package.path, plan.version)
            _lifecycle.build_release(plan.package, self._root)
            if git.is_clean(root):
                # Already stamped: a release squash-merged but never
                # published leaves main carrying exactly these
                # entries and versions, and re-preparing is the
                # recovery. A clean tree is that state, not a fault.
                print(
                    f"  {plan.package.name} v{plan.version}:"
                    " already stamped on the base; nothing to commit"
                )
                continue
            git.commit_all(
                root, f"chore(release): {plan.package.name} v{plan.version}"
            )
        if not git.is_clean(root):
            # Only the manifest changed: every member was already
            # stamped on the base (a merged release whose publish
            # failed), and the manifest alone is what lets the
            # squash's discovery still name the whole set.
            git.commit_all(root, "chore(release): the set manifest")
        verify_set(self._root, plans)
        # Every member's wheel exists before any leg runs; a
        # failed leg still tears the whole branch down, commits
        # included, so nothing unvalidated survives.
        release_dirs = _wheel_dists(plans)
        for plan in plans:
            if plan.package.member in kept:
                print(
                    f"  {plan.package.name} v{plan.version}: legs kept from the"
                    " discarded prepare; the base did not move its directory"
                )
                continue
            validate_member(self._root, plan, release_dirs)
        prepared = True
    finally:
        if not prepared:
            rollback_prepare(self._root, self._members, floor_changes)
            git.switch(root, self.base)
            git.delete_branch(root, self.branch)
    title = release_title([(plan.package.name, plan.version) for plan in plans])
    body = (
        "## Release summary\n"
        + "\n".join(f"- **{plan.package.name}** v{plan.version}" for plan in plans)
        + f"\n\nMined-At: {mined_at}"
    )
    return Submission(title=title, body=body)

on_merged

on_merged() -> None

The merge point dispatches the wave; follow it to its verdict.

The wave's run is awaited by its id, then followed the way ci.status --point=release --wait follows it, so the act ends with the wave's own verdict and exit; the receipt tags say when each member is done. A wave timeout of zero reports the merge and names the dispatch verb as the confirmation instead of waiting: the engine's own tests run against a forge with no merge point.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def on_merged(self) -> None:
    """The merge point dispatches the wave; follow it to its verdict.

    The wave's run is awaited by its id, then followed the way
    ``ci.status --point=release --wait`` follows it, so the act
    ends with the wave's own verdict and exit; the receipt tags
    say when each member is done. A wave timeout of zero reports
    the merge and names the dispatch verb as the confirmation
    instead of waiting: the engine's own tests run against a
    forge with no merge point.
    """
    if self._wave_timeout <= 0:
        print(
            "  merged; the merge point dispatches the wave, confirm it with"
            f" `{footman.prog()} workflow.release.dispatch`"
        )
        return
    transient = Transient(interval=_WAVE_POLL)
    before = {run.id for run in _wave_runs_answered(self._repo, transient)}
    run_id = await_wave(
        self._repo,
        before=before,
        timeout=self._wave_timeout,
        transient=transient,
    )
    if run_id is None:
        fail(
            "merged, but no release wave appeared within"
            f" {self._wave_timeout:.0f}s: the merge point's dispatch job"
            " runs after main's own verdict, so a red main or a slow"
            " queue is the usual cause. The recovery is"
            f" `{footman.prog()} workflow.release.dispatch` from any"
            " checkout, which answers green once the wave is up."
        )
    print(
        f"  merged; the merge point dispatched the wave, run {run_id}; the"
        " receipt tags say when each member is done"
    )
    run = next(
        (r for r in _wave_runs_answered(self._repo, transient) if r.id == run_id),
        None,
    )
    if run is None:
        return
    from livery.workshop._ci_tasks import follow_run

    code = follow_run(self._repo, "release", run, timeout=self._wave_timeout)
    self._trace_the_chain()
    if code:
        raise SystemExit(code)

release_name

release_name(members: tuple[str, ...]) -> str

The workflow name a set earns: its directories, sorted and +-joined.

A set whose joined directories run past NAME_LIMIT is named by its size and a digest of them instead, so the branch stays short and the same set always earns the same name.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def release_name(members: tuple[str, ...]) -> str:
    """The workflow name a set earns: its directories, sorted and ``+``-joined.

    A set whose joined directories run past `NAME_LIMIT` is named by
    its size and a digest of them instead, so the branch stays short
    and the same set always earns the same name.
    """
    joined = "+".join(sorted(members))
    if len(joined) <= NAME_LIMIT:
        return f"release/{joined}"
    import hashlib

    digest = hashlib.sha256(joined.encode("utf-8")).hexdigest()[:12]
    return f"release/{len(members)}-packages-{digest}"

resolve_set

resolve_set(root: Path, paths: tuple[str, ...]) -> tuple[Package, ...]

The named packages, in dependency order; every name must exist.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def resolve_set(root: Path, paths: tuple[str, ...]) -> tuple[Package, ...]:
    """The named packages, in dependency order; every name must exist."""
    packages = {p.path: p for p in discover_packages(root)}
    chosen: list[Package] = []
    for path in paths:
        package = packages.get(path) or packages.get(f"packages/{path}")
        if package is None:
            known = ", ".join(sorted(packages))
            fail(f"{path} is not a workspace package; members: {known}")
        chosen.append(package)
    return order_topologically(tuple(chosen))

derive_plans

derive_plans(root: Path, members: tuple[Package, ...]) -> tuple[MemberPlan, ...]

Each member's next version, every member refused when unchanged.

Runs before the branch is cut, from read-only state: a refusal here has nothing to undo. A member whose bump equals its newest released tag has nothing unreleased, and minting a number the index already has is refused with the options. The tag is the judge, never the stamped version: a stamp can land without its release cutting, and judging by it would strand that release (the same rule livery.workshop._release.prepare_release keeps).

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def derive_plans(root: Path, members: tuple[Package, ...]) -> tuple[MemberPlan, ...]:
    """Each member's next version, every member refused when unchanged.

    Runs before the branch is cut, from read-only state: a refusal
    here has nothing to undo. A member whose bump equals its newest
    released tag has nothing unreleased, and minting a number the
    index already has is refused with the options. The tag is the
    judge, never the stamped version: a stamp can land without its
    release cutting, and judging by it would strand that release
    (the same rule livery.workshop._release.prepare_release keeps).
    """
    from livery.workshop._release import _last_released

    plans: list[MemberPlan] = []
    unchanged: list[str] = []
    for package in members:
        released = _last_released(root, package)
        derived = derive_version(root, package, released=released)
        if not derived or derived == released:
            unchanged.append(package.member)
            continue
        plans.append(MemberPlan(package=package, version=derived))
    if unchanged:
        names = ", ".join(unchanged)
        fail(
            f"nothing unreleased touches: {names}. Options: drop them from"
            " the set (release the rest now); or, if a hollow re-release is"
            " truly meant, stamp a version explicitly with"
            f" `{footman.prog()} release.prepare <path> <version>`."
        )
    return tuple(plans)

member_pairs_at

member_pairs_at(root: Path, ref: str) -> list[tuple[str, str]] | None

(distribution, version) for each member in the member list at ref.

Each name is read from the member's contract as committed at ref, so the answer describes that commit alone. None when ref carries no readable list.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def member_pairs_at(root: Path, ref: str) -> list[tuple[str, str]] | None:
    """(distribution, version) for each member in the member list at *ref*.

    Each name is read from the member's contract as committed at
    *ref*, so the answer describes that commit alone. None when *ref*
    carries no readable list.
    """
    import tomllib

    from livery.workshop._publish import MANIFEST, read_manifest

    recorded = read_manifest(git.file_at(root, ref, MANIFEST))
    if recorded is None:
        return None
    pairs: list[tuple[str, str]] = []
    for directory, version in recorded:
        try:
            contract = tomllib.loads(
                git.file_at(root, ref, f"packages/{directory}/workshop.toml")
            )
            name = str(contract.get("name") or directory)
        except tomllib.TOMLDecodeError:
            name = directory
        pairs.append((name, version))
    return pairs

bump_set_floors

bump_set_floors(root: Path, plans: tuple[MemberPlan, ...]) -> list[str]

Raise floors between co-released members through the stamp phase; the files.

Within the set only (contract: a solo release never moves a floor): each member's stamp phase runs at the version it declares now, with every other member's version as its floors, so the version stays for prepare_release to stamp. Each step raises the floors in its own manifests, and the base those of the member's [[depends]] edges, as livery.workshop._lifecycle.stamp says. The files are the ones the phase reported, relative to root.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def bump_set_floors(root: Path, plans: tuple[MemberPlan, ...]) -> list[str]:
    """Raise floors between co-released members through the stamp phase; the files.

    Within the set only (contract: a solo release never moves a
    floor): each member's stamp phase runs at the version it declares
    now, with every other member's version as its floors, so the
    version stays for `prepare_release` to stamp. Each step raises the
    floors in its own manifests, and the base those of the member's
    ``[[depends]]`` edges, as `livery.workshop._lifecycle.stamp` says.
    The files are the ones the phase reported, relative to *root*.
    """
    if len(plans) < 2:
        return []
    changed: list[str] = []
    for plan in plans:
        package = plan.package
        floors = {
            other.package.path: other.version
            for other in plans
            if other.package.path != package.path
        }
        current = _lifecycle.current_version(package)
        stamped = _lifecycle.stamp(package, root, current, floors=floors)
        changed += [
            (package.directory / name).relative_to(root).as_posix() for name in stamped
        ]
    return changed

rollback_prepare

rollback_prepare(root: Path, members: tuple[Package, ...], reported: Sequence[str] = ()) -> None

Restore exactly the files prepare writes; never raises.

The error being unwound is the one worth seeing, so this raises nothing of its own: each member's changelog, contract and version files return to HEAD, and so do the files the stamp phase reported raising floors in (relative to root), the set's manifest and the workspace lock the stamp refreshed. One of these files on disk that HEAD lacks is one prepare created, as a first release's changelog and manifest are, and it is removed, so the switch back to the base does not carry it along. Each restore reads HEAD, never the index: a commit that failed (a signing agent that refused) has already staged every change, and a restore from the index would keep them. Each path the rollback could not put back is printed with the reason, and the other paths are put back all the same.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def rollback_prepare(
    root: Path, members: tuple[Package, ...], reported: Sequence[str] = ()
) -> None:
    """Restore exactly the files prepare writes; never raises.

    The error being unwound is the one worth seeing, so this raises
    nothing of its own: each member's changelog, contract and version
    files return to HEAD, and so do the files the stamp phase
    *reported* raising floors in (relative to *root*), the set's
    manifest and the workspace lock the stamp refreshed. One of these
    files on disk that HEAD lacks is one prepare created, as a first
    release's changelog and manifest are, and it is removed, so the
    switch back to the base does not carry it along. Each restore reads
    HEAD, never the index: a commit that failed (a signing agent that
    refused) has already staged every change, and a restore from the
    index would keep them. Each path the rollback could not put back is
    printed with the reason, and the other paths are put back all the
    same.
    """
    for path, reason in _put_back(root, _prepare_paths(root, members, reported)):
        print(f"  the rollback could not restore {path}: {reason}")

verify_set

verify_set(root: Path, plans: tuple[MemberPlan, ...]) -> None

Run the publish job's own checks over the stamped set, before any leg.

The wave refuses a member whose version homes disagree with its tag, whose release notes are unsound, or whose floor names an unreleased version, and it refuses only after the release has merged. The same checks on the stamped tree refuse before a release pull request exists. The set's own tags count as released, as the wave counts them.

Raises:

Type Description
Failed

as the publish job's check refuses, naming the member and each problem.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def verify_set(root: Path, plans: tuple[MemberPlan, ...]) -> None:
    """Run the publish job's own checks over the stamped set, before any leg.

    The wave refuses a member whose version homes disagree with its tag,
    whose release notes are unsound, or whose floor names an unreleased
    version, and it refuses only after the release has merged. The same
    checks on the stamped tree refuse before a release pull request
    exists. The set's own tags count as released, as the wave counts them.

    Raises:
        Failed: as the publish job's check refuses, naming the member and
            each problem.
    """
    from livery.workshop._release import verify_release

    coreleased = frozenset(f"{plan.package.path}/v{plan.version}" for plan in plans)
    for plan in plans:
        verify_release(
            root, f"{plan.package.path}/v{plan.version}", coreleased=coreleased
        )

proved_resolutions

proved_resolutions(root: Path, package: Package) -> tuple[tuple[str, ...], str]

The resolutions package's release tests at, and the file that listed them.

The package's own [release] prove wins; the workspace's is the default; without either the release tests at livery.workshop._release_driver.DEFAULT_RESOLUTIONS, and the file is empty. The contract's judge refuses a word other than the three and a word listed twice, so the list holds each at most once, in the order the legs run.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def proved_resolutions(root: Path, package: Package) -> tuple[tuple[str, ...], str]:
    """The resolutions *package*'s release tests at, and the file that listed them.

    The package's own `[release] prove` wins; the workspace's is the
    default; without either the release tests at
    [livery.workshop._release_driver.DEFAULT_RESOLUTIONS][], and the
    file is empty. The contract's judge refuses a word other than the
    three and a word listed twice, so the list holds each at most
    once, in the order the legs run.
    """
    from livery.workshop._contract import load_contract

    for contract in (package.directory / "workshop.toml", root / "workshop.toml"):
        if not contract.is_file():
            continue
        release = load_contract(contract).get("release") or {}
        if PROVE in release:
            listed = {str(word) for word in release[PROVE]}
            where = contract.relative_to(root).as_posix()
            return tuple(word for word in RESOLUTIONS if word in listed), where
    return DEFAULT_RESOLUTIONS, ""

validate_member

validate_member(root: Path, plan: MemberPlan, release_dirs: tuple[Path, ...]) -> None

Run the member's test phase isolated once per resolution it proves; report each.

One leg per resolution (livery.workshop._release_driver.proved_resolutions), in the order of livery.workshop._release_driver.RESOLUTIONS, so the floor leg runs before the latest leg; a list from a contract is named with its file. The report names what each leg resolved per co-member and sibling: every workspace member but the one under test. The caller builds every set member's wheel first: the legs' find-links name each sibling's dist/, so a later member's wheel must exist before an earlier member's floor leg resolves.

A member whose extensions add no isolated test, as a conan package's do, has no venv to isolate: its own gate already built and ran ctest, so the legs skip saying why.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def validate_member(
    root: Path, plan: MemberPlan, release_dirs: tuple[Path, ...]
) -> None:
    """Run the member's test phase isolated once per resolution it proves; report each.

    One leg per resolution
    ([livery.workshop._release_driver.proved_resolutions][]), in the
    order of [livery.workshop._release_driver.RESOLUTIONS][], so the
    floor leg runs before the latest leg; a list from a contract is
    named with its file. The report names what each leg resolved per
    co-member and sibling: every workspace member but the one under
    test. The caller builds every set member's wheel first: the legs'
    find-links name each sibling's ``dist/``, so a later member's
    wheel must exist before an earlier member's floor leg resolves.

    A member whose extensions add no isolated test, as a conan
    package's do, has no venv to isolate: its own gate already built
    and ran ctest, so the legs skip saying why.
    """
    if not _lifecycle.has_isolated_test(plan.package):
        print(
            f"  {plan.package.name}: isolated legs skip (its extensions add no"
            " isolated test, since it publishes no wheel; its own gate builds"
            " and tests)"
        )
        return
    legs, where = proved_resolutions(root, plan.package)
    if where:
        listed = ", ".join(legs) or "nothing, so no leg runs"
        print(f"  {plan.package.name}: [release] {PROVE} in {where} lists {listed}")
    members = {_normalised(package.name) for package in discover_packages(root)}
    own = _normalised(plan.package.name)
    for leg in legs:
        resolved = _lifecycle.isolated_test(
            plan.package, root, resolution=leg, release_dirs=release_dirs
        )
        siblings = {
            name: version
            for name, version in sorted(resolved.items())
            if _normalised(name) in members and _normalised(name) != own
        }
        listed = ", ".join(f"{n} {v}" for n, v in siblings.items()) or "no siblings"
        print(f"  {plan.package.name} {leg} leg: {listed}")

require_verified_base

require_verified_base(repo: Repository, root: Path, base: str, *, force: bool = False, timeout: float = BASE_TIMEOUT, poll: float = BASE_POLL) -> None

Wait for the base's own push CI to be green; stop on red or skip.

Branch protection only ever judged PR heads, and a release publishes the base's tree, so the base's push run is the only vouching there is. Green, not merely not-red; red is a verdict waiting cannot improve; a skip-ci tip will never get a run; an unreachable forge fails open, the engine's UNKNOWN story says it better.

Zero reported contexts after minutes means run creation itself failed, and every forge can do it: Gitea's actions queue could wedge before 1.27.3, GitHub silently drops a push's workflow-run creation under load, and GitLab can never mint the pipeline (a job-queue backlog, or workflow rules evaluating to nothing). The combined-status read reports all three identically, so detection is uniform; the safe remedy is not (whether a tool may push to the base varies per forge and protection), so the silent tip gets a printed teaching naming the fresh-push-event remedy, never an automatic push. The timeout tells the two conditions apart: a run that reported and hung sends the reader to the runners, a tip that never got a run names run creation.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def require_verified_base(
    repo: Repository,
    root: Path,
    base: str,
    *,
    force: bool = False,
    timeout: float = BASE_TIMEOUT,
    poll: float = BASE_POLL,
) -> None:
    """Wait for the base's own push CI to be green; stop on red or skip.

    Branch protection only ever judged PR heads, and a release
    publishes the base's tree, so the base's push run is the only
    vouching there is. Green, not merely not-red; red is a verdict
    waiting cannot improve; a skip-ci tip will never get a run; an
    unreachable forge fails open, the engine's UNKNOWN story says it
    better.

    Zero reported contexts after minutes means run creation itself
    failed, and every forge can do it: Gitea's actions queue could
    wedge before 1.27.3, GitHub silently drops a push's workflow-run
    creation under load, and GitLab can never mint the pipeline (a
    job-queue backlog, or workflow rules evaluating to nothing). The
    combined-status read
    reports all three identically, so detection is uniform; the safe
    remedy is not (whether a tool may push to the base varies per
    forge and protection), so the silent tip gets a printed teaching
    naming the fresh-push-event remedy, never an automatic push. The
    timeout tells the two conditions apart: a run that reported and
    hung sends the reader to the runners, a tip that never got a run
    names run creation.
    """
    if force:
        print("  base verification skipped (--force-unverified-base)")
        return
    if _base_tree_verified(root, base):
        return
    announced = False
    silent_since: float | None = None
    nudged = False
    ever_reported = False

    def read() -> bool | Pending:
        nonlocal announced, silent_since, nudged, ever_reported
        try:
            git.fetch(root)
            sha = git.remote_head(root, base)
            status = repo.checks.status(sha) if sha else None
        except ForgeError:
            raise
        except Exception as error:
            # The base gate fails open: a tree nobody can vouch for
            # releases, and the reason is said rather than swallowed.
            print(f"  {base}'s CI could not be read ({error}); releasing unverified")
            return True
        if status is None or status.state == "success":
            return True
        if status.state == "failure":
            fail(
                f"{base}'s own CI is red, and a release publishes that tree."
                f" Fix {base} first (`{footman.prog()} ci.logs` on it names"
                " the job), or"
                " release with --force-unverified-base if you accept an"
                " unvouched tree."
            )
        if "[skip ci]" in git.commit_message(root, sha):
            fail(
                f"{base}'s tip carries a skip-ci marker, so CI will never"
                " report on it. Push a commit CI can run, or"
                " --force-unverified-base to accept it unverified."
            )
        now = time.monotonic()
        if status.contexts:
            ever_reported = True
            silent_since = None
        elif silent_since is None:
            silent_since = now
        elif not nudged and now - silent_since >= SILENT_NUDGE_AFTER:
            nudged = True
            print(
                f"  {base}'s tip has had no CI run for"
                f" {SILENT_NUDGE_AFTER // 60} min; a fresh push event may be"
                " needed (an empty commit mints one)."
            )
        if not announced:
            announced = True
            print(
                f"  waiting for {base}'s own CI before releasing (up to"
                f" {BASE_TIMEOUT // 60} min)"
            )
        return Pending()

    try:
        follow(
            repo,
            read,
            subject=f"{base}'s own CI",
            interval=poll,
            timeout=timeout,
            quiet=None,
        )
    except ForgeUnreachable as exc:
        print(exc.line)
        print(f"  releasing unverified: {base}'s CI could not be read")
    except FollowTimedOut:
        # Not started and hanging are different problems with
        # different remedies, so the timeout names the one that
        # actually happened.
        if ever_reported:
            fail(
                f"{base} reported a run but never went green within"
                f" {timeout / 60:.0f} minutes. Check the runners"
                f" (`{footman.prog()} status --watch` on a branch follows"
                " a run), or"
                " --force-unverified-base."
            )
        fail(
            f"{base}'s tip never got a CI run in {timeout / 60:.0f}"
            " minutes: run creation itself failed, and waiting cannot"
            " fix that. A fresh push event mints a run (an empty"
            " commit, or its PR merged), or --force-unverified-base."
        )

release_title

release_title(pairs: Sequence[tuple[str, str]]) -> str

The release pull request's title: each member with its version, or a count.

The title is the squash commit's headline, and arming hands it to GitHub's auto-merge, which refuses a long one. A set whose title would pass TITLE_LIMIT characters is counted instead; the pull request's body and the commit's body list every member.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def release_title(pairs: Sequence[tuple[str, str]]) -> str:
    """The release pull request's title: each member with its version, or a count.

    The title is the squash commit's headline, and arming hands it to
    GitHub's auto-merge, which refuses a long one. A set whose title
    would pass `TITLE_LIMIT` characters is counted instead; the pull
    request's body and the commit's body list every member.
    """
    listed = ", ".join(f"{name} v{version}" for name, version in pairs)
    title = f"chore(release): released {listed}"
    if len(title) <= TITLE_LIMIT:
        return title
    counted = "1 package" if len(pairs) == 1 else f"{len(pairs)} packages"
    return f"chore(release): released {counted}"

runs_the_train

runs_the_train(branch: str) -> bool

Whether workflow.release on branch is the release train, not the dev act.

main and the engine's reserved workflow/ branches release; any other branch builds a dev wheel straight from its commit.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def runs_the_train(branch: str) -> bool:
    """Whether `workflow.release` on *branch* is the release train, not the dev act.

    ``main`` and the engine's reserved ``workflow/`` branches release;
    any other branch builds a dev wheel straight from its commit.
    """
    return branch == "main" or branch.startswith("workflow/")

fresh_receipts

fresh_receipts(root: Path) -> None

Fetch origin's tags, so a derivation reads every receipt a wave cut.

A release wave tags its receipts on the remote, and this checkout holds them only after a fetch: a derivation from stale tags names versions the index already has. A checkout with no origin has only its own tags to read; one that cannot reach origin derives from its own and says so.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def fresh_receipts(root: Path) -> None:
    """Fetch origin's tags, so a derivation reads every receipt a wave cut.

    A release wave tags its receipts on the remote, and this checkout
    holds them only after a fetch: a derivation from stale tags names
    versions the index already has. A checkout with no origin has only
    its own tags to read; one that cannot reach origin derives from its
    own and says so.
    """
    if not git.has_remote(root, "origin"):
        return
    try:
        git.fetch_tags(root)
    except git.GitError as error:
        print(
            "  origin could not be fetched, so the versions come from this"
            f" checkout's own tags: {error}"
        )

local_release

local_release(root: Path, members: tuple[Package, ...]) -> None

Everything that stays on this machine, then the stamps roll back.

Derive, stamp (so the built wheels carry the would-be versions), build, run the isolated legs, print the would-be release, restore the tree; dist/ and the report remain. Publishing consent is never asked because nothing leaves the machine. The derivation reads origin's receipts, fetched first, so it names the versions the armed act would (livery.workshop._release_driver.fresh_receipts). Before any of it, the act refuses while a file it would write has changes of its own, since the restore would discard them; a change anywhere else in the tree is left alone.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def local_release(root: Path, members: tuple[Package, ...]) -> None:
    """Everything that stays on this machine, then the stamps roll back.

    Derive, stamp (so the built wheels carry the would-be versions),
    build, run the isolated legs, print the would-be release, restore
    the tree; ``dist/`` and the report remain. Publishing consent is
    never asked because nothing leaves the machine. The derivation
    reads origin's receipts, fetched first, so it names the versions
    the armed act would ([livery.workshop._release_driver.fresh_receipts][]).
    Before any of it, the act refuses while a file it would write has
    changes of its own, since the restore would discard them; a change
    anywhere else in the tree is left alone.
    """
    _require_unchanged(root, members)
    fresh_receipts(root)
    plans = derive_plans(root, members)
    print("  act: local; nothing leaves this machine")
    floor_changes: list[str] = []
    try:
        floor_changes = bump_set_floors(root, plans)
        for plan in plans:
            prepare_release(root, plan.package.path, plan.version)
            _lifecycle.build_release(plan.package, root)
        verify_set(root, plans)
        release_dirs = _wheel_dists(plans)
        for plan in plans:
            validate_member(root, plan, release_dirs)
        listed = ", ".join(f"{plan.package.name} v{plan.version}" for plan in plans)
        print(f"  would release: {listed}")
        print("  wheels in each member's dist/; the tree is restored")
    finally:
        rollback_prepare(root, members, floor_changes)

await_wave

await_wave(repo: Repository, *, before: set[int], timeout: float = 1800.0, interval: float = _WAVE_POLL, transient: Transient | None = None) -> int | None

The id of the newest wave run not in before, or None when none appears.

Any state counts: a wave that already finished by the time the poll saw it is still the wave that ran, and a confirmation that demanded a live run would miss a fast forge. An unreadable poll is retried within transient's budget.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def await_wave(
    repo: Repository,
    *,
    before: set[int],
    timeout: float = 1800.0,
    interval: float = _WAVE_POLL,
    transient: Transient | None = None,
) -> int | None:
    """The id of the newest wave run not in *before*, or ``None`` when none appears.

    Any state counts: a wave that already finished by the time the
    poll saw it is still the wave that ran, and a confirmation that
    demanded a live run would miss a fast forge. An unreadable poll is
    retried within *transient*'s budget.
    """

    def new_run() -> int | Pending:
        new = [run for run in _wave_runs(repo) if run.id not in before]
        return new[0].id if new else Pending()

    try:
        return follow(
            repo,
            new_run,
            subject=_WAVE_SUBJECT,
            interval=interval,
            timeout=timeout,
            quiet=None,
            transient=transient,
        )
    except ForgeUnreachable as exc:
        fail(exc.line.strip())
    except FollowTimedOut:
        return None

dispatch_flow

dispatch_flow(root: Path, repo: Repository, *, base: str = 'main', at: str = '', workshop: str = '', again: bool = False, timeout: float = 60.0, interval: float = 2.0) -> list[str]

Dispatch the wave for a merged, unpublished release, or say why not.

Reads the manifest on origin/<base> after a fetch, whatever commit this checkout stands on, or at at, an older release squash a later release has moved past. A checkout behind the base would otherwise send the wave to the squash a later release took over. workshop names a released driver for the wave instead of the squash's own, the recovery for a wave whose workshop was the fault; empty runs the squash's. Green when there is none, or when every member's receipt tag is already on the remote: the manifest is permanent residue of the last release, so presence is not the signal, missing receipts are. A wave already in flight is reported green with its run id. A wave that already ran at the squash with the squash's own driver and ended failure is reported green too, with its run and the recoveries, and nothing is dispatched: the same wave fails the same way, and every merge would otherwise start one more copy of it. again dispatches it anyway, the gesture by hand once the cause is gone, and a named workshop is another wave. Otherwise the wave is dispatched on base with the commit that stamped the manifest as its ref input, never this run's own sha, so an unrelated merge landing first cannot move the wave onto another tree; the dispatch is confirmed by the run id that appears, or refused with the reason. Remote state only, receipts by ls-remote and runs by the forge, so any checkout answers the same as CI.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def dispatch_flow(
    root: Path,
    repo: Repository,
    *,
    base: str = "main",
    at: str = "",
    workshop: str = "",
    again: bool = False,
    timeout: float = 60.0,
    interval: float = 2.0,
) -> list[str]:
    """Dispatch the wave for a merged, unpublished release, or say why not.

    Reads the manifest on ``origin/<base>`` after a fetch, whatever
    commit this checkout stands on, or at *at*, an older release squash
    a later release has moved past. A checkout behind the base would
    otherwise send the wave to the squash a later release took over.
    *workshop* names a released driver for the wave instead of the
    squash's own, the recovery for a wave whose workshop was the fault;
    empty runs the squash's. Green when there is none, or when
    every member's receipt tag is already on the remote: the
    manifest is permanent residue of the last release, so presence
    is not the signal, missing receipts are. A wave already in
    flight is reported green with its run id. A wave that already ran
    at the squash with the squash's own driver and ended failure is
    reported green too, with its run and the recoveries, and nothing
    is dispatched: the same wave fails the same way, and every merge
    would otherwise start one more copy of it. *again* dispatches it
    anyway, the gesture by hand once the cause is gone, and a named
    *workshop* is another wave. Otherwise the wave is dispatched on
    *base* with the commit that stamped the manifest as its ``ref``
    input, never this run's own sha, so an unrelated merge landing
    first cannot move the wave onto another tree; the dispatch is
    confirmed by the run id that appears, or refused with the reason.
    Remote state only, receipts by ``ls-remote`` and runs by the
    forge, so any checkout answers the same as CI.
    """
    from livery.workshop._publish import MANIFEST, read_manifest

    where = at or _base_ref(root, base)
    text = git.file_at(root, where, MANIFEST)
    recorded = read_manifest(text) if text else None
    if not recorded:
        return [f"  no release manifest at {where}: nothing to dispatch"]
    cut = set(git.remote_tags(root))
    receipts = [f"packages/{directory}/v{version}" for directory, version in recorded]
    missing = [tag for tag in receipts if tag not in cut]
    if not missing:
        return [f"  every receipt is cut ({', '.join(receipts)}): nothing to dispatch"]
    live = [run for run in _wave_runs(repo) if run.status != "completed"]
    if live:
        return [
            f"  the wave is already in flight: run {live[0].id};"
            f" uncut so far: {', '.join(missing)}"
        ]
    stamping = at or git.last_commit_touching(root, MANIFEST, ref=where)
    if not stamping:
        return [
            f"  {MANIFEST} is at {where} but no commit touches it: nothing to dispatch"
        ]
    _require_release_squash(root, stamping, base)
    if not workshop and not again:
        failed = _failed_wave_at(root, repo, stamping)
        if failed is not None:
            prog = footman.prog()
            return [
                f"  a wave already ran at {stamping[:12]} and ended failure: run"
                f" {failed.id} ({repo.web_url()}/actions/runs/{failed.id}); the same"
                f" wave fails the same way, so none is dispatched. Uncut:"
                f" {', '.join(missing)}",
                f"  to run it again once the cause is gone: `{prog}"
                " workflow.release.dispatch --again`; with a released driver:"
                f" `--workshop=<version>`; to give the release up: `{prog}"
                " workflow.release --abandon`",
            ]
    seen = {run.id for run in _wave_runs(repo)}
    inputs = {"ref": stamping}
    if workshop:
        inputs["workshop"] = workshop
    try:
        repo.checks.dispatch(RELEASE_WORKFLOW, ref=base, inputs=inputs)
    except ForgeError as error:
        # Red, never a printed line: the merge point's verdict is the
        # exit code, and a wave that did not start leaves the release
        # uncut until someone reads the log.
        fail(
            f"the forge refused the dispatch: {error}; uncut:"
            f" {', '.join(missing)}. Nothing started; on GitHub the job"
            " needs the actions: write grant, and the recovery by hand"
            f" is `{footman.prog()} workflow.release.dispatch`"
        )
    import time

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        new = [run for run in _wave_runs(repo) if run.id not in seen]
        if new:
            driver = f" driven by {workshop}" if workshop else ""
            return [
                f"  dispatched the wave at {stamping[:12]}{driver}: run {new[0].id};"
                f" uncut: {', '.join(missing)}"
            ]
        time.sleep(interval)
    return [
        "  the dispatch was accepted but no wave run appeared within"
        f" {timeout:.0f}s; re-run `{footman.prog()} workflow.release.dispatch`,"
        " which reports a wave that has since appeared"
    ]

newest_release_squash

newest_release_squash(root: Path, base: str = 'main') -> tuple[str, str]

The newest release squash on the base, as (sha, subject); ("", "") when none.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def newest_release_squash(root: Path, base: str = "main") -> tuple[str, str]:
    """The newest release squash on the base, as (sha, subject); ("", "") when none."""
    from livery.workshop._publish import mined_at

    for sha, subject in git.recent_commits(root, 50, ref=_base_ref(root, base)):
        if subject.startswith("chore(release): released") and mined_at(
            git.commit_message(root, sha)
        ):
            return sha, subject
    return "", ""

pending_release_waves

pending_release_waves(root: Path, base: str = 'main') -> tuple[tuple[str, tuple[str, ...]], ...]

Every recent release squash whose receipts are not all cut, oldest first.

A merged release whose wave died leaves the squash on the base with the stamps and changelogs landed and receipt tags missing. Re-preparing from that state derives an empty release (measured: an empty pull request the forge never agrees to merge), so the recovery is the wave at the squash, never a new pull request. Every release squash in the base's recent history is consulted, so a later release never strands an earlier died wave, and a checkout standing on a release branch still finds the squash it was merged as. A later release squash naming a package takes over that package's uncut receipt, so a squash abandoned for a new release (fm workflow.release --abandon) is never offered again. Each entry is the squash sha and its missing receipt tags.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def pending_release_waves(
    root: Path, base: str = "main"
) -> tuple[tuple[str, tuple[str, ...]], ...]:
    """Every recent release squash whose receipts are not all cut, oldest first.

    A merged release whose wave died leaves the squash on the base
    with the stamps and changelogs landed and receipt tags missing.
    Re-preparing from that state derives an empty release (measured:
    an empty pull request the forge never agrees to merge), so the
    recovery is the wave at the squash, never a new pull request.
    Every release squash in the base's recent history is consulted, so
    a later release never strands an earlier died wave, and a checkout
    standing on a release branch still finds the squash it was merged
    as. A later release squash naming a package takes over that
    package's uncut receipt, so a squash abandoned for a new release
    (`fm workflow.release --abandon`) is never offered again. Each
    entry is the squash sha and its missing receipt tags.
    """
    from livery.workshop._publish import discover_release

    cut = set(git.remote_tags(root))
    pending: list[tuple[str, tuple[str, ...]]] = []
    # Newest first: the packages a later release squash names.
    taken: set[str] = set()
    for sha, subject in git.recent_commits(root, 50, ref=_base_ref(root, base)):
        if not subject.startswith("chore(release): released"):
            continue
        released = discover_release(root, sha)
        missing = tuple(
            f"{package.path}/v{version}"
            for package, version in released
            if f"{package.path}/v{version}" not in cut and package.path not in taken
        )
        taken.update(package.path for package, _version in released)
        if missing:
            pending.append((sha, missing))
    pending.reverse()
    return tuple(pending)

pending_release_wave

pending_release_wave(root: Path) -> tuple[str, tuple[str, ...]] | None

The oldest release squash with an uncut receipt, or None.

The set-blind selection, for a dispatch with no set named: recoveries run in order, oldest first.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def pending_release_wave(root: Path) -> tuple[str, tuple[str, ...]] | None:
    """The oldest release squash with an uncut receipt, or None.

    The set-blind selection, for a dispatch with no set named:
    recoveries run in order, oldest first.
    """
    waves = pending_release_waves(root)
    return waves[0] if waves else None

pending_release_wave_for

pending_release_wave_for(root: Path, members: tuple[Package, ...]) -> tuple[str, tuple[str, ...]] | None

The oldest uncut squash whose receipts touch members, or None.

A release of one set must find its own died wave even when an older squash of another set is uncut too: that squash is the other set's recovery, named by the caller, never a reason to prepare this set again from a tree already stamped.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def pending_release_wave_for(
    root: Path, members: tuple[Package, ...]
) -> tuple[str, tuple[str, ...]] | None:
    """The oldest uncut squash whose receipts touch *members*, or None.

    A release of one set must find its own died wave even when an
    older squash of another set is uncut too: that squash is the
    other set's recovery, named by the caller, never a reason to
    prepare this set again from a tree already stamped.
    """
    for sha, missing in pending_release_waves(root):
        if uncut_in_set(missing, members):
            return (sha, missing)
    return None

uncut_in_set

uncut_in_set(missing: tuple[str, ...], members: tuple[Package, ...]) -> tuple[str, ...]

The uncut receipts, packages/<member>/v<x>, that belong to members.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def uncut_in_set(
    missing: tuple[str, ...], members: tuple[Package, ...]
) -> tuple[str, ...]:
    """The uncut receipts, `packages/<member>/v<x>`, that belong to *members*."""
    names = {member.member for member in members}
    return tuple(tag for tag in missing if receipt_member(tag) in names)

workflow_release

workflow_release(*paths: str, armed: Annotated[bool, doc('arm the release PR to merge on green')] = False, local: Annotated[bool, doc('derive, build, validate, report; nothing leaves the machine')] = False, force_unverified_base: Annotated[bool, doc("release without waiting for the base's own CI")] = False, workshop: Annotated[str, doc('a released livery-workshop version to drive a re-dispatched wave')] = '', abandon: Annotated[bool, doc('prepare a new release over a died wave of this set instead of re-dispatching it')] = False) -> None

Release a set of packages: the branch decides the act.

Names the set positionally (packages/forge or just forge). On a main-family branch this is the release train: one PR, receipts per member, re-running the recovery at every step; --armed follows the pull request to its squash and the wave to its verdict, from main, the way submit --armed follows a feature pull request, and an unarmed run returns at once. On any other branch it is the dev act: a wheel straight from the branch at a dev version, published only to the configured custom index after a confirmation, no reserved branch, no PR, no tags. --local is everything that stays on this machine, on either branch mode. --workshop applies only to the recovery of a died wave: the named release drives the wave in place of the squash's own workshop. --abandon gives up that recovery: when no released workshop can drive the died wave, a new release of the set takes its uncut receipts over.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
@release_group.default(interactive=True)
def workflow_release(
    *paths: str,
    armed: Annotated[bool, doc("arm the release PR to merge on green")] = False,
    local: Annotated[
        bool, doc("derive, build, validate, report; nothing leaves the machine")
    ] = False,
    force_unverified_base: Annotated[
        bool, doc("release without waiting for the base's own CI")
    ] = False,
    workshop: Annotated[
        str, doc("a released livery-workshop version to drive a re-dispatched wave")
    ] = "",
    abandon: Annotated[
        bool,
        doc(
            "prepare a new release over a died wave of this set instead of"
            " re-dispatching it"
        ),
    ] = False,
) -> None:
    """Release a set of packages: the branch decides the act.

    Names the set positionally (``packages/forge`` or just ``forge``).
    On a main-family branch this is the release train: one PR,
    receipts per member, re-running the recovery at every step;
    ``--armed`` follows the pull request to its squash and the wave
    to its verdict, from main, the way ``submit --armed`` follows a
    feature pull request, and an unarmed run returns at once. On
    any other branch it is the dev act: a wheel straight from the
    branch at a dev version, published only to the configured custom
    index after a confirmation, no reserved branch, no PR, no tags.
    ``--local`` is everything that stays on this machine, on either
    branch mode. ``--workshop`` applies only to the recovery of a
    died wave: the named release drives the wave in place of the
    squash's own workshop. ``--abandon`` gives up that recovery: when
    no released workshop can drive the died wave, a new release of
    the set takes its uncut receipts over.
    """
    from livery.workshop._dev_release import dev_release
    from livery.workshop._extensions import workspace_root
    from livery.workshop._forge_lane import this_repository

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    if not paths:
        fail(
            f"name the set: `{footman.prog()} workflow.release forge` (one package) or"
            f" `{footman.prog()} workflow.release forge workshop` (an atomic set)"
        )
    members = resolve_set(root, tuple(paths))
    branch = git.current_branch(root)
    if not branch:
        fail(
            "HEAD is detached, and the branch decides the act. Check out a"
            " branch (main for the release train, any feature branch for a"
            " dev build), then run this again."
        )
    if not runs_the_train(branch):
        dev_release(root, members, local=local)
        return
    if local:
        local_release(root, members)
        return
    print(f"  act: release train, from '{branch}'")
    pending = pending_release_wave_for(root, members)
    repo = this_repository(root)
    if abandon:
        if pending is None:
            fail(
                "--abandon gives up a died wave of this set, and no release"
                " squash has an uncut receipt in it; drop the flag to prepare"
                " a release"
            )
        squash, missing = pending
        print(
            f"  release squash {squash[:12]} abandoned; this release takes over"
            f" its uncut receipts: {', '.join(uncut_in_set(missing, members))}"
        )
        pending = None
    if pending is not None:
        squash, missing = pending
        print(f"  release squash {squash[:12]} has uncut receipts:")
        for name in missing:
            print(f"    {name}")
        # CI publishes, never this machine: the wave is dispatched
        # at the squash, the duplicate-tolerant wave walks past what
        # an earlier attempt already did, and nothing new prepares.
        print("  dispatching the wave at the squash; nothing new prepares")
        for line in dispatch_flow(root, repo, at=squash, workshop=workshop):
            print(line)
        print("  re-run to release work newer than the squash")
        return
    for squash, missing in pending_release_waves(root):
        # An uncut receipt outside this set is that set's recovery,
        # named so a person can run it; this release goes ahead.
        inside = uncut_in_set(missing, members)
        missing = tuple(tag for tag in missing if tag not in inside)
        if not missing:
            continue
        others = " ".join(sorted({receipt_member(tag) for tag in missing}))
        print(
            f"  release squash {squash[:12]} has uncut receipts outside this"
            f" set: {', '.join(missing)}; `{footman.prog()} workflow.release"
            f" {others}` re-dispatches its wave"
        )
    if workshop:
        fail(
            "--workshop pins the driver of a re-dispatched wave, and no"
            " release squash has an uncut receipt; drop the flag to prepare"
            " a release"
        )
    run_release(
        partial(
            ReleaseDriver,
            root,
            repo,
            members,
            armed=armed,
            force_unverified_base=force_unverified_base,
        ),
        repo,
        root,
        armed=armed,
    )

run_release

run_release(make_driver: Callable[[], ReleaseDriver], repo: Repository, root: Path, *, armed: bool) -> None

Drive a release through the engine; an armed one re-derives a stale set.

An armed release whose follow ends red because the base moved under its set prepares again on the moved base and follows again, up to [livery.workshop._release_driver.REDERIVE_LIMIT] prepares in all; any other red is the release's verdict and exits with it.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def run_release(
    make_driver: Callable[[], ReleaseDriver],
    repo: Repository,
    root: Path,
    *,
    armed: bool,
) -> None:
    """Drive a release through the engine; an armed one re-derives a stale set.

    An armed release whose follow ends red because the base moved
    under its set prepares again on the moved base and follows again,
    up to [livery.workshop._release_driver.REDERIVE_LIMIT] prepares
    in all; any other red is the release's verdict and exits with it.
    """
    for attempt in range(1, REDERIVE_LIMIT + 1):
        driver = make_driver()
        try:
            run_workflow(driver, repo, root)
            return
        except SystemExit:
            if (
                not armed
                or attempt == REDERIVE_LIMIT
                or not set_moved(repo, root, driver.name)
            ):
                raise
            print(
                f"  {driver.branch}: the base moved under the set while its pull"
                f" request waited; re-deriving ({attempt} of"
                f" {REDERIVE_LIMIT - 1} re-derives)"
            )

set_moved

set_moved(repo: Repository, root: Path, name: str) -> bool

Whether release name's open pull request is stale in its set's paths.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def set_moved(repo: Repository, root: Path, name: str) -> bool:
    """Whether release *name*'s open pull request is stale in its set's paths."""
    from livery.workshop._workflow_state import workflow_states

    git.fetch(root)
    return any(
        wf.name == name and wf.blocker.name == "STALE_SET"
        for wf in workflow_states(repo, root)
    )

workflow_release_dispatch

workflow_release_dispatch(at: Annotated[str, doc("an older release squash to dispatch instead of HEAD's")] = '', workshop: Annotated[str, doc('a released livery-workshop version to drive the wave')] = '', again: Annotated[bool, doc('dispatch although a wave already failed at the squash')] = False) -> None

Dispatch the release wave for a merged, unpublished release; green otherwise.

The merge point's last task, and the recovery gesture by hand: it reads the manifest at HEAD and the receipts on the remote, so on a normal day it prints green, after a died merge run it dispatches, a wave in flight is reported with its run id, and a wave that already failed at the squash is reported with its run and dispatched again only on --again. --at names an older release squash a later release has moved past; --workshop names a released driver for a wave whose own workshop was the fault.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
@release_group.task(name="dispatch")
def workflow_release_dispatch(
    at: Annotated[
        str, doc("an older release squash to dispatch instead of HEAD's")
    ] = "",
    workshop: Annotated[
        str, doc("a released livery-workshop version to drive the wave")
    ] = "",
    again: Annotated[
        bool, doc("dispatch although a wave already failed at the squash")
    ] = False,
) -> None:
    """Dispatch the release wave for a merged, unpublished release; green otherwise.

    The merge point's last task, and the recovery gesture by hand:
    it reads the manifest at HEAD and the receipts on the remote, so
    on a normal day it prints green, after a died merge run it
    dispatches, a wave in flight is reported with its run id, and a
    wave that already failed at the squash is reported with its run
    and dispatched again only on ``--again``. ``--at`` names an older
    release squash a later release has moved past; ``--workshop``
    names a released driver for a wave whose own workshop was the
    fault.
    """
    from livery.workshop._extensions import workspace_root
    from livery.workshop._forge_lane import this_repository

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    for line in dispatch_flow(
        root, this_repository(root), at=at, workshop=workshop, again=again
    ):
        print(line)

workflow_release_check_title

workflow_release_check_title(title: Annotated[str, doc('the PR title CI observed')] = '') -> None

Verify a release PR's title against the release's member list.

The publish wave discovers a release from the squash's member list; the title is presentation. This job keeps the two consistent: the gate job runs this first, so a title that no longer names what the list prepared is refused before the union and the verdict, and the merge waits for a person to fix the title. Without --title the title comes from the runner's event payload; a run that is not a pull request, or a pull request off a release branch, is green here and says so.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
@release_group.task(name="check-title", hidden=True)
def workflow_release_check_title(
    title: Annotated[str, doc("the PR title CI observed")] = "",
) -> None:
    """Verify a release PR's title against the release's member list.

    The publish wave discovers a release from the squash's member
    list; the title is presentation. This job keeps the two
    consistent: the gate job runs this first, so a title that no
    longer names what the list prepared is refused before the
    union and the verdict, and the merge waits for a person to fix
    the title. Without ``--title`` the title
    comes from the runner's event payload; a run that is not a pull
    request, or a pull request off a release branch, is green here
    and says so.
    """
    from livery.workshop._extensions import workspace_root

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    if not title:
        # The shell passes no title: the event payload names it, and
        # names the head branch too. An explicit --title is always
        # checked, whatever branch the runner is on.
        from livery.workshop._ci_context import event_payload

        pull = (event_payload() or {}).get("pull_request") or {}
        title = str(pull.get("title") or "")
        if not title:
            print("  not a pull request: no title to check")
            return
        head_ref = str((pull.get("head") or {}).get("ref") or "")
        if head_ref and not head_ref.startswith("workflow/release/"):
            print(f"  {head_ref} is not a release branch: nothing to check")
            return
    branch = git.current_branch(root)
    recorded = member_pairs_at(root, "HEAD")
    if not recorded:
        print(f"  {branch}: no release member list; nothing to check")
        return
    expected = release_title(recorded)
    if title and title != expected:
        fail(
            f"the PR title does not match what the member list prepared:\n"
            f"    title:    {title}\n    prepared: {expected}\n"
            "  The title is presentation rebuilt from the branch's"
            " member list; restore it or re-run workflow.release."
        )
    print(f"  title matches the prepared release: {expected}")

workflow_release_check_fresh

workflow_release_check_fresh(head: Annotated[str, doc("the pull request's head branch")] = '', base: Annotated[str, doc('the branch it merges into')] = '') -> None

Refuse a release pull request whose base moved in its set's paths.

The gate job runs this last, so the time between the check and the merge it allows is as short as the forge makes it. The release's manifest names its members and the commit the prepare mined at; a commit the base gained since then under a member's directory is code the stamped changelog does not cover, and the squash's publish would refuse it after the merge, where nothing can fix the squash. Refused here, the pull request waits while workflow.release re-derives it in place. Without --head the branches come from the runner's event payload; a run that is not a pull request, or one off a release branch, is green and says so.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
@release_group.task(name="check-fresh", hidden=True)
def workflow_release_check_fresh(
    head: Annotated[str, doc("the pull request's head branch")] = "",
    base: Annotated[str, doc("the branch it merges into")] = "",
) -> None:
    """Refuse a release pull request whose base moved in its set's paths.

    The gate job runs this last, so the time between the check and
    the merge it allows is as short as the forge makes it. The
    release's manifest names its members and the commit the prepare
    mined at; a commit the base gained since then under a member's
    directory is code the stamped changelog does not cover, and the
    squash's publish would refuse it after the merge, where nothing
    can fix the squash. Refused here, the pull request waits while
    `workflow.release` re-derives it in place. Without ``--head`` the
    branches come from the runner's event payload; a run that is not
    a pull request, or one off a release branch, is green and says so.
    """
    import json

    from livery.workshop._extensions import workspace_root
    from livery.workshop._publish import MANIFEST, read_manifest

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    if not head:
        from livery.workshop._ci_context import event_payload

        pull = (event_payload() or {}).get("pull_request") or {}
        if not pull:
            print("  not a pull request: nothing to check")
            return
        head = str((pull.get("head") or {}).get("ref") or "")
        base = base or str((pull.get("base") or {}).get("ref") or "")
    if not head.startswith("workflow/release/"):
        print(f"  {head or 'this branch'} is not a release branch: nothing to check")
        return
    base = base or "main"
    text = git.file_at(root, "HEAD", MANIFEST)
    pairs = read_manifest(text) if text else None
    mined = ""
    if pairs:
        with contextlib.suppress(ValueError, TypeError, AttributeError):
            mined = str(json.loads(text).get("mined-at") or "")
    if not pairs or not mined:
        print(f"  {MANIFEST} records no mining point: nothing to check")
        return
    git.fetch(root)
    paths = tuple(f"packages/{directory}" for directory, _ in pairs)
    moved = git.log_paths(root, f"{mined}..origin/{base}", paths)
    if moved:
        listed = "\n".join(f"    {subject}" for subject in moved)
        members = " ".join(directory for directory, _ in pairs)
        fail(
            f"{base} moved under this release since its prepare at"
            f" {mined[:12]}:\n{listed}\n  Merged, the squash would ship code"
            " its changelog does not cover. `"
            f"{footman.prog()} workflow.release {members}` re-derives it in"
            " place; an armed release does that itself."
        )
    print(f"  fresh: {base} has not moved under {', '.join(paths)} since {mined[:12]}")

workflow_release_publish

workflow_release_publish(ref: Annotated[str, doc('the release squash; empty means HEAD')] = '', prebuilt: Annotated[bool, doc('trust the dist/ the run collected for each member a job builds')] = False) -> None

Publish the squash at --ref: the wave, receipts cut per member.

The CI entry point after a release PR merges, and the recovery entry when a publish died mid-wave: everything already tagged is walked past. --ref exists because HEAD usually moves past the squash before a recovery runs. Each member publishes to the registry of the ecosystem its extensions release it to, and the wave reads what that registry serves through the probe they answer: the resolved index for a python package, the resolved conan target for a conan recipe that names a reference. --prebuilt says the jobs of the run already built the members they build before the wave, the workspace's job-built-members answer: a platform-wheel member's dist/ holds the wheels collected from every platform, a conan member's the caches saved on every host, and the wave publishes them instead of building on this runner alone. Inside CI the wave decides that for itself: such a member whose dist/ already holds a file was fed by the run, since a runner's checkout starts with none.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
@release_group.task(name="publish", hidden=True)
def workflow_release_publish(
    ref: Annotated[str, doc("the release squash; empty means HEAD")] = "",
    prebuilt: Annotated[
        bool, doc("trust the dist/ the run collected for each member a job builds")
    ] = False,
) -> None:
    """Publish the squash at --ref: the wave, receipts cut per member.

    The CI entry point after a release PR merges, and the recovery
    entry when a publish died mid-wave: everything already tagged is
    walked past. ``--ref`` exists because HEAD usually moves past the
    squash before a recovery runs. Each member publishes to the
    registry of the ecosystem its extensions release it to, and the
    wave reads what that registry serves through the probe they answer:
    the resolved index for a python package, the resolved conan target
    for a conan recipe that names a reference.
    ``--prebuilt`` says the jobs of the run already built the members
    they build before the wave, the workspace's ``job-built-members``
    answer: a platform-wheel member's dist/ holds the wheels collected
    from every platform, a conan member's the caches saved on every
    host, and the wave publishes them instead of building on this
    runner alone. Inside CI the wave decides that for itself: such a
    member whose dist/ already holds a file was fed by the run, since
    a runner's checkout starts with none.
    """
    import os

    from livery.workshop._extensions import workspace_root
    from livery.workshop._publish import Registry, publish_release
    from livery.workshop._registries import resolve_registry

    root = workspace_root()
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    target = resolve_registry(root, "python")
    if not target.publish_url:
        from livery.workshop._dev_release import INDEX_VAR

        fail(
            "no publish address resolved for python: the declaration"
            " names only a read index, and an upload endpoint is"
            " never defaulted. Declare [registries.python] publish in"
            f" workshop.toml, or set {INDEX_VAR}."
        )
    if not prebuilt:
        prebuilt = collected_wheels(root, ref)
    # Each member's probe is its extensions' answer, asked once and
    # polled through the wave's whole wait.
    probes: dict[str, Registry] = {}

    def registry_for(package: Package) -> Registry:
        probe = probes.get(package.path)
        if probe is None:
            probe = probes[package.path] = _lifecycle.registry(package)
        return probe

    receipts = publish_release(
        root,
        registry_for,
        ref=ref,
        index_url=target.publish_url,
        # UV_PUBLISH_TOKEN is the explicit override; the resolved
        # target's credential is the same seam the probe reads, so a
        # forge registry publishes with the lane token unprompted.
        token=os.environ.get("UV_PUBLISH_TOKEN", "") or target.token,
        prebuilt=prebuilt,
    )
    print(f"  wave: {len(receipts)} member(s) published")

collected_wheels

collected_wheels(root: Path, ref: str) -> bool

Whether the run collected what a job built for this wave, judged inside CI alone.

The members a job builds before the wave are the workspace's job-built-members answer. A runner's checkout starts with no dist/, so a file in such a member's dist/ was collected from that job's artifact, and the wave trusts the collection; each member it trusts is printed with its job. Outside CI a dist/ may hold a stale local build, and the wave builds as asked.

Source code in packages/workshop/src/livery/workshop/_release_driver.py
def collected_wheels(root: Path, ref: str) -> bool:
    """Whether the run collected what a job built for this wave, judged inside CI alone.

    The members a job builds before the wave are the workspace's
    ``job-built-members`` answer. A runner's checkout starts with no
    dist/, so a file in such a member's dist/ was collected from that
    job's artifact, and the wave trusts the collection; each member it
    trusts is printed with its job. Outside CI a dist/ may hold a stale
    local build, and the wave builds as asked.
    """
    from livery.workshop._ci_context import run_context
    from livery.workshop._publish import collected, discover_release
    from livery.workshop._queries import JOB_BUILT_MEMBERS, answer

    if run_context() is None:
        return False
    built = answer(root, JOB_BUILT_MEMBERS)
    fed = False
    for package, _version in discover_release(root, ref or git.head_sha(root)):
        job = built.get(package.path)
        if job is not None and collected(package):
            print(
                f"  prebuilt: {package.name}: the run collected what the {job} job"
                " built"
            )
            fed = True
    return fed