Skip to content

livery.workshop._release

livery.workshop._release

The release train's verbs: prepare, the tag check, the driver, and verify.

fm release.check-tag checks a release tag against the tree: the tag, the pyproject version, the __version__, and the changelog must all agree, and every [[depends]] floor must resolve to a tag that has actually been released; the release wave runs the same check for every member before anything uploads. fm release.prepare stamps a version into those same places, idempotently. fm release.verify runs a member's verify phase: its latest released version installed alone and tested at the release tag.

Classes:

Name Description
ReleasePlan

One verified release: the package and the version the tag names.

Functions:

Name Description
verify_release

Check tag against the tree; every finding fails verbatim.

release_check_tag

Check tag against the tree: the release wave's check, run by hand.

prepare_release

Stamp a release into path's places; what changed.

release_prepare

Stamp a release: version derived from the commits unless given.

release_verify

Verify a member's latest released wheel against its own tests.

release_driver

Install the released workshop workshop names over the checkout's own.

Attributes:

Name Type Description
release

release module-attribute

release = group('release', help="The release train's CI entries")

ReleasePlan dataclass

ReleasePlan(package: Package, version: str)

One verified release: the package and the version the tag names.

Attributes:

Name Type Description
package Package

The workspace package being released.

version str

The semver the tag carries.

package instance-attribute

package: Package

version instance-attribute

version: str

verify_release

verify_release(root: Path, tag: str, *, coreleased: frozenset[str] = frozenset()) -> ReleasePlan

Check tag against the tree; every finding fails verbatim.

The agreements checked: the tag names an existing package; the version homes its set answers (pyproject, and one __version__ for a package holding the runtime's language with a root module, the recipe's version for conan) carry the tag's version; the release notes provider, when one is mounted, finds the version's notes sound; and every [[depends]] floor names a version whose release tag exists, so nothing ships depending on an unreleased floor.

Source code in packages/workshop/src/livery/workshop/_release.py
def verify_release(
    root: Path, tag: str, *, coreleased: frozenset[str] = frozenset()
) -> ReleasePlan:
    """Check *tag* against the tree; every finding fails verbatim.

    The agreements checked: the tag names an existing package; the
    version homes its set answers (pyproject, and one ``__version__``
    for a package holding the runtime's language with a root module,
    the recipe's ``version`` for conan) carry the tag's version; the
    release notes provider, when one is mounted, finds the version's
    notes sound; and every ``[[depends]]`` floor names a version whose
    release tag exists, so nothing ships depending on an unreleased
    floor.
    """
    found = release_tag(tag)
    if found is None:
        fail(f"tag {tag!r} does not match packages/<member>/v<semver>")
    path, version = found
    packages = {package.path: package for package in discover_packages(root)}
    package = packages.get(path)
    if package is None:
        fail(f"tag names {path}, which is not a workspace package")
    problems = []
    declared = _lifecycle.current_version(package)
    if declared != version:
        problems.append(f"tag says {version}, the package declares {declared}")
    notes = _release_notes.release_notes(root)
    if notes is not None:
        problems += notes.verify(package, version)
    if holds_runtime_language(package):
        # The modules the set's stamp writes the version into: a
        # package's __init__.py. A package with none, a namespace with
        # no public names, carries its version in its manifest alone.
        # The name, not the suffix: a recipe the stamp raises floors in
        # is python source and declares no __version__.
        modules = [
            home
            for home in _lifecycle.version_files(package)
            if home.name == "__init__.py" and home.is_file()
        ]
        stamp = f'__version__ = "{version}"'
        if modules and not any(
            stamp in module.read_text("utf-8") for module in modules
        ):
            problems.append(f"no __init__.py under src/ declares {stamp}")
    released = set(git.tags(root))
    for edge in package.depends:
        if not edge.floor:
            continue
        wanted = f"{edge.path}/v{edge.floor}"
        if wanted in coreleased:
            # An atomic set's intra-set floor: the wave cuts the
            # dependency's receipt before this member publishes, so
            # the tag it names exists by the time any consumer looks.
            continue
        if wanted not in released:
            problems.append(
                f"the floor on {edge.path} is {edge.floor}, and no tag"
                f" {wanted} exists: floors must name released versions"
            )
    if problems:
        fail(f"release {tag} refused:\n  " + "\n  ".join(problems))
    return ReleasePlan(package=package, version=version)

release_check_tag

release_check_tag(tag: Annotated[str, doc('the release tag, packages/<member>/v<semver>')]) -> None

Check tag against the tree: the release wave's check, run by hand.

In GitHub Actions the verified package name is appended to $GITHUB_OUTPUT as package=<name> for the build step.

Source code in packages/workshop/src/livery/workshop/_release.py
@release.task(name="check-tag", hidden=True)
def release_check_tag(
    tag: Annotated[str, doc("the release tag, packages/<member>/v<semver>")],
) -> None:
    """Check *tag* against the tree: the release wave's check, run by hand.

    In GitHub Actions the verified package name is appended to
    ``$GITHUB_OUTPUT`` as ``package=<name>`` for the build step.
    """
    plan = verify_release(_root(), tag)
    print(f"  verified: {plan.package.name} {plan.version} from {tag}")
    output = os.environ.get("GITHUB_OUTPUT", "")
    if output:
        with Path(output).open("a", encoding="utf-8") as handle:
            handle.write(f"package={plan.package.name}\n")

prepare_release

prepare_release(root: Path, path: str, version: str = '') -> list[str]

Stamp a release into path's places; what changed.

Without version, it is derived from the conventional commits under the package's paths since its last release tag (livery.workshop._versions), and the release notes provider writes the entry the commits earn. A given version wins and gets an empty entry for the human to write. With no provider mounted, the version is stamped and no notes are written. Idempotent either way: a place already carrying the version is left alone.

Source code in packages/workshop/src/livery/workshop/_release.py
def prepare_release(root: Path, path: str, version: str = "") -> list[str]:
    """Stamp a release into *path*'s places; what changed.

    Without *version*, it is derived from the conventional commits
    under the package's paths since its last release tag
    (livery.workshop._versions), and the release notes provider
    writes the entry the commits earn. A given *version* wins and
    gets an empty entry for the human to write. With no provider
    mounted, the version is stamped and no notes are written.
    Idempotent either way: a place already carrying the version is
    left alone.
    """
    packages = {package.path: package for package in discover_packages(root)}
    package = packages.get(path)
    if package is None:
        fail(f"{path} is not a workspace package")
    entry_body = ""
    notes = _release_notes.release_notes(root)
    if not version:
        derived = derive_version(root, package)
        released = _last_released(root, package)
        if not derived or derived == released:
            # The derivation answers with the last tag's version when
            # nothing unreleased touches the package. The tag is the
            # receipt (never the stamped pyproject: a stamp can land
            # without its release cutting, and judging by it would
            # strand that release forever). Releasing again would
            # republish the same code under a version the index
            # already has.
            print(f"  nothing to release: no unreleased commits touch {path}")
            return []
        version = derived
        entry_body = notes.entry(root, package, version) if notes else ""
        since = released or "the beginning"
        print(f"  derived {version} from the commits since {since}")
    if not _SEMVER_RE.fullmatch(version):
        fail(f"version {version!r} is not <major>.<minor>.<patch>")
    if notes and not entry_body and version != _last_released(root, package):
        # An explicitly passed version regenerates a stranded entry
        # too: the driver hands prepare the derived version, and a
        # heading without its tag under-documents what actually
        # ships either way.
        entry_body = notes.entry(root, package, version)
    changed = _lifecycle.stamp(package, root, version)
    if notes is not None:
        changed += notes.record(package, version, entry_body)
    else:
        print(f"  {_release_notes.NO_PROVIDER}")
    lock = root / "uv.lock"
    if changed and lock.is_file():
        # The lock records every member's version, so a stamp without
        # a refresh leaves the lock claiming the old one: the first
        # sync after the release rewrites it, and the dirty tree then
        # blocks the train's own re-run. Refreshing here puts the lock
        # line inside the commit that stamps the version.
        before_lock = lock.read_bytes()
        result = tools.uv.opts(cwd=root, nofail=True, recorded=False)("lock")
        if result.code != 0:
            fail(
                f"uv lock after stamping {version} failed:"
                f"\n{result.stdout}{result.stderr}"
            )
        if lock.read_bytes() != before_lock:
            changed.append("uv.lock")
    return changed

release_prepare

release_prepare(path: Annotated[str, doc('the package, e.g. packages/workshop')], version: Annotated[str, doc('the semver to stamp; empty derives it')] = '') -> None

Stamp a release: version derived from the commits unless given.

The derived path reads what the unreleased commits earn, and the release notes provider writes the entry they make, for review. A package with nothing unreleased is refused rather than given a new number. A given version wins and leaves the entry for the human. fm release.check-tag is the check that everything agrees before the tag is cut.

Source code in packages/workshop/src/livery/workshop/_release.py
@release.task(name="prepare", hidden=True)
def release_prepare(
    path: Annotated[str, doc("the package, e.g. packages/workshop")],
    version: Annotated[str, doc("the semver to stamp; empty derives it")] = "",
) -> None:
    """Stamp a release: version derived from the commits unless given.

    The derived path reads what the unreleased commits earn, and the
    release notes provider writes the entry they make, for review. A
    package with nothing unreleased is refused rather than given a new
    number. A given version wins and
    leaves the entry for the human. ``fm release.check-tag`` is the
    check that everything agrees before the tag is cut.
    """
    for name in prepare_release(_root(), path, version):
        print(f"  stamped: {name}")

release_verify

release_verify(member: Annotated[str, doc("the member's directory under packages/")], *, python: Annotated[str, doc('the interpreter version for the plain environment')] = '', extras: Annotated[str, doc('extras to install with the wheel, comma-joined')] = '', report: Annotated[bool, doc('file or extend the marker issue on red; the default inside CI')] = False) -> None

Verify a member's latest released wheel against its own tests.

The member's verify phase: the pairing a consumer gets, the wheel the registry serves installed into a plain environment beside the tests at the release tag, imported from site-packages. The nightly point schedules it through [[ci.schedule]]; by hand it answers the same. A red verification fails, and inside CI (or with --report) files or extends the marker issue through the forge first.

Source code in packages/workshop/src/livery/workshop/_release.py
@release.task(name="verify")
def release_verify(
    member: Annotated[str, doc("the member's directory under packages/")],
    *,
    python: Annotated[
        str, doc("the interpreter version for the plain environment")
    ] = "",
    extras: Annotated[str, doc("extras to install with the wheel, comma-joined")] = "",
    report: Annotated[
        bool, doc("file or extend the marker issue on red; the default inside CI")
    ] = False,
) -> None:
    """Verify a member's latest released wheel against its own tests.

    The member's verify phase: the pairing a consumer gets, the wheel
    the registry serves installed into a plain environment beside the
    tests at the release tag, imported from site-packages. The nightly
    point schedules it through ``[[ci.schedule]]``; by hand it answers
    the same. A red verification fails, and inside CI (or with
    ``--report``) files or extends the marker issue through the forge
    first.
    """
    import sys

    from livery.forge import SimpleRegistry
    from livery.workshop._ci_context import run_context
    from livery.workshop._registries import resolve_registry
    from livery.workshop._verify import verify_flow

    root = _root()
    packages = {p.member: p for p in discover_packages(root)}
    package = packages.get(member)
    if package is None:
        fail(
            f"no member {member!r} under packages/; the members are"
            f" {', '.join(sorted(packages)) or 'none'}"
        )
    # The target's url is the read index itself, the wave's probe
    # reads it the same way; the install points uv at the same index.
    target = resolve_registry(root, "python")
    registry = SimpleRegistry(target.url, token=target.token)
    repo = None
    if report or run_context() is not None:
        from livery.workshop._forge_lane import this_repository

        repo = this_repository(root)
    verify_flow(
        root,
        package,
        python=python or f"{sys.version_info.major}.{sys.version_info.minor}",
        registry=registry,
        index=target.url,
        extras=extras,
        repo=repo,
    )

release_driver

release_driver(workshop: Annotated[str, doc("a released livery-workshop version to drive the wave; empty keeps the checkout's")] = '') -> None

Install the released workshop workshop names over the checkout's own.

The wave's recovery for a run whose own workshop was the fault: a re-dispatch names a released driver, and this step installs it before the wave's verbs run, so they run under it. Empty, the checkout's workshop drives the wave and nothing is installed; a re-run then does what the first run did.

Source code in packages/workshop/src/livery/workshop/_release.py
@release.task(name="driver", hidden=True)
def release_driver(
    workshop: Annotated[
        str,
        doc(
            "a released livery-workshop version to drive the wave; empty keeps"
            " the checkout's"
        ),
    ] = "",
) -> None:
    """Install the released workshop *workshop* names over the checkout's own.

    The wave's recovery for a run whose own workshop was the fault: a
    re-dispatch names a released driver, and this step installs it
    before the wave's verbs run, so they run under it. Empty, the
    checkout's workshop drives the wave and nothing is installed; a
    re-run then does what the first run did.
    """
    import livery.toolroom.tools as tools

    if not workshop:
        print("  driver: the checkout's own workshop drives the wave")
        return
    from livery.workshop._ci_generate import DRIVER_DIST

    tools.uv("pip", "install", f"{DRIVER_DIST}=={workshop}")
    print(f"  driver: {DRIVER_DIST} {workshop} installed over the checkout's")