1"""The release train's verbs: prepare, the tag check, the driver, and verify.
3``fm release.check-tag`` checks a release tag against the tree: the
4tag, the ``pyproject`` version, the ``__version__``, and the changelog
5must all agree, and every ``[[depends]]`` floor must resolve to a tag
6that has actually been released; the release wave runs the same check
7for every member before anything uploads. ``fm release.prepare``
8stamps a version into those same places, idempotently.
9``fm release.verify`` runs a member's verify phase: its latest
10released version installed alone and tested at the release tag.
11"""
13from __future__ import annotations
15import os
16import re
17from dataclasses import dataclass
18from pathlib import Path
19from typing import Annotated
21import livery.toolroom.tools as tools
22from livery import git
23from livery.footman import doc, fail, group
24from livery.workshop import _lifecycle, _release_notes
25from livery.workshop._extensions import workspace_root
26from livery.workshop._packages import (
27 Package,
28 discover_packages,
29 holds_runtime_language,
30 release_tag,
31)
32from livery.workshop._versions import derive_version
34release = group("release", help="The release train's CI entries")
36_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
39def _root() -> Path:
40 root = workspace_root()
41 if root is None:
42 fail("no workspace: no workshop.toml above the working directory")
43 return root
46@dataclass(frozen=True)
47class ReleasePlan:
48 """One verified release: the package and the version the tag names.
50 Attributes:
51 package: The workspace package being released.
52 version: The semver the tag carries.
53 """
55 package: Package
56 version: str
59def verify_release(
60 root: Path, tag: str, *, coreleased: frozenset[str] = frozenset()
61) -> ReleasePlan:
62 """Check *tag* against the tree; every finding fails verbatim.
64 The agreements checked: the tag names an existing package; the
65 version homes its set answers (pyproject, and one ``__version__``
66 for a package holding the runtime's language with a root module,
67 the recipe's ``version`` for conan) carry the tag's version; the
68 release notes provider, when one is mounted, finds the version's
69 notes sound; and every ``[[depends]]`` floor names a version whose
70 release tag exists, so nothing ships depending on an unreleased
71 floor.
72 """
73 found = release_tag(tag)
74 if found is None:
75 fail(f"tag {tag!r} does not match packages/<member>/v<semver>")
76 path, version = found
77 packages = {package.path: package for package in discover_packages(root)}
78 package = packages.get(path)
79 if package is None:
80 fail(f"tag names {path}, which is not a workspace package")
81 problems = []
82 declared = _lifecycle.current_version(package)
83 if declared != version:83 ↛ 84line 83 didn't jump to line 84 because the condition on line 83 was never true
84 problems.append(f"tag says {version}, the package declares {declared}")
85 notes = _release_notes.release_notes(root)
86 if notes is not None:
87 problems += notes.verify(package, version)
88 if holds_runtime_language(package):
89 # The modules the set's stamp writes the version into: a
90 # package's __init__.py. A package with none, a namespace with
91 # no public names, carries its version in its manifest alone.
92 # The name, not the suffix: a recipe the stamp raises floors in
93 # is python source and declares no __version__.
94 modules = [
95 home
96 for home in _lifecycle.version_files(package)
97 if home.name == "__init__.py" and home.is_file()
98 ]
99 stamp = f'__version__ = "{version}"'
100 if modules and not any(
101 stamp in module.read_text("utf-8") for module in modules
102 ):
103 problems.append(f"no __init__.py under src/ declares {stamp}")
104 released = set(git.tags(root))
105 for edge in package.depends:
106 if not edge.floor:106 ↛ 107line 106 didn't jump to line 107 because the condition on line 106 was never true
107 continue
108 wanted = f"{edge.path}/v{edge.floor}"
109 if wanted in coreleased:
110 # An atomic set's intra-set floor: the wave cuts the
111 # dependency's receipt before this member publishes, so
112 # the tag it names exists by the time any consumer looks.
113 continue
114 if wanted not in released:
115 problems.append(
116 f"the floor on {edge.path} is {edge.floor}, and no tag"
117 f" {wanted} exists: floors must name released versions"
118 )
119 if problems:
120 fail(f"release {tag} refused:\n " + "\n ".join(problems))
121 return ReleasePlan(package=package, version=version)
124@release.task(name="check-tag", hidden=True)
125def release_check_tag(
126 tag: Annotated[str, doc("the release tag, packages/<member>/v<semver>")],
127) -> None:
128 """Check *tag* against the tree: the release wave's check, run by hand.
130 In GitHub Actions the verified package name is appended to
131 ``$GITHUB_OUTPUT`` as ``package=<name>`` for the build step.
132 """
133 plan = verify_release(_root(), tag)
134 print(f" verified: {plan.package.name} {plan.version} from {tag}")
135 output = os.environ.get("GITHUB_OUTPUT", "")
136 if output:
137 with Path(output).open("a", encoding="utf-8") as handle:
138 handle.write(f"package={plan.package.name}\n")
141def _last_released(root: Path, package: Package) -> str:
142 """The newest released version *package*'s tags carry, or empty.
144 Tags are the release identity and its receipt; a stamped version
145 without its tag is an unfinished release, not a finished one.
146 """
147 from livery.workshop._update import latest_released
149 return latest_released(git.tags(root)).get(package.path, "")
152def prepare_release(root: Path, path: str, version: str = "") -> list[str]:
153 """Stamp a release into *path*'s places; what changed.
155 Without *version*, it is derived from the conventional commits
156 under the package's paths since its last release tag
157 (livery.workshop._versions), and the release notes provider
158 writes the entry the commits earn. A given *version* wins and
159 gets an empty entry for the human to write. With no provider
160 mounted, the version is stamped and no notes are written.
161 Idempotent either way: a place already carrying the version is
162 left alone.
163 """
164 packages = {package.path: package for package in discover_packages(root)}
165 package = packages.get(path)
166 if package is None:
167 fail(f"{path} is not a workspace package")
168 entry_body = ""
169 notes = _release_notes.release_notes(root)
170 if not version:
171 derived = derive_version(root, package)
172 released = _last_released(root, package)
173 if not derived or derived == released:
174 # The derivation answers with the last tag's version when
175 # nothing unreleased touches the package. The tag is the
176 # receipt (never the stamped pyproject: a stamp can land
177 # without its release cutting, and judging by it would
178 # strand that release forever). Releasing again would
179 # republish the same code under a version the index
180 # already has.
181 print(f" nothing to release: no unreleased commits touch {path}")
182 return []
183 version = derived
184 entry_body = notes.entry(root, package, version) if notes else ""
185 since = released or "the beginning"
186 print(f" derived {version} from the commits since {since}")
187 if not _SEMVER_RE.fullmatch(version):
188 fail(f"version {version!r} is not <major>.<minor>.<patch>")
189 if notes and not entry_body and version != _last_released(root, package):
190 # An explicitly passed version regenerates a stranded entry
191 # too: the driver hands prepare the derived version, and a
192 # heading without its tag under-documents what actually
193 # ships either way.
194 entry_body = notes.entry(root, package, version)
195 changed = _lifecycle.stamp(package, root, version)
196 if notes is not None:
197 changed += notes.record(package, version, entry_body)
198 else:
199 print(f" {_release_notes.NO_PROVIDER}")
200 lock = root / "uv.lock"
201 if changed and lock.is_file():
202 # The lock records every member's version, so a stamp without
203 # a refresh leaves the lock claiming the old one: the first
204 # sync after the release rewrites it, and the dirty tree then
205 # blocks the train's own re-run. Refreshing here puts the lock
206 # line inside the commit that stamps the version.
207 before_lock = lock.read_bytes()
208 result = tools.uv.opts(cwd=root, nofail=True, recorded=False)("lock")
209 if result.code != 0:209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true
210 fail(
211 f"uv lock after stamping {version} failed:"
212 f"\n{result.stdout}{result.stderr}"
213 )
214 if lock.read_bytes() != before_lock:214 ↛ 216line 214 didn't jump to line 216 because the condition on line 214 was always true
215 changed.append("uv.lock")
216 return changed
219@release.task(name="prepare", hidden=True)
220def release_prepare(
221 path: Annotated[str, doc("the package, e.g. packages/workshop")],
222 version: Annotated[str, doc("the semver to stamp; empty derives it")] = "",
223) -> None:
224 """Stamp a release: version derived from the commits unless given.
226 The derived path reads what the unreleased commits earn, and the
227 release notes provider writes the entry they make, for review. A
228 package with nothing unreleased is refused rather than given a new
229 number. A given version wins and
230 leaves the entry for the human. ``fm release.check-tag`` is the
231 check that everything agrees before the tag is cut.
232 """
233 for name in prepare_release(_root(), path, version):
234 print(f" stamped: {name}")
237@release.task(name="verify")
238def release_verify(
239 member: Annotated[str, doc("the member's directory under packages/")],
240 *,
241 python: Annotated[
242 str, doc("the interpreter version for the plain environment")
243 ] = "",
244 extras: Annotated[str, doc("extras to install with the wheel, comma-joined")] = "",
245 report: Annotated[
246 bool, doc("file or extend the marker issue on red; the default inside CI")
247 ] = False,
248) -> None:
249 """Verify a member's latest released wheel against its own tests.
251 The member's verify phase: the pairing a consumer gets, the wheel
252 the registry serves installed into a plain environment beside the
253 tests at the release tag, imported from site-packages. The nightly
254 point schedules it through ``[[ci.schedule]]``; by hand it answers
255 the same. A red verification fails, and inside CI (or with
256 ``--report``) files or extends the marker issue through the forge
257 first.
258 """
259 import sys
261 from livery.forge import SimpleRegistry
262 from livery.workshop._ci_context import run_context
263 from livery.workshop._registries import resolve_registry
264 from livery.workshop._verify import verify_flow
266 root = _root()
267 packages = {p.member: p for p in discover_packages(root)}
268 package = packages.get(member)
269 if package is None:
270 fail(
271 f"no member {member!r} under packages/; the members are"
272 f" {', '.join(sorted(packages)) or 'none'}"
273 )
274 # The target's url is the read index itself, the wave's probe
275 # reads it the same way; the install points uv at the same index.
276 target = resolve_registry(root, "python")
277 registry = SimpleRegistry(target.url, token=target.token)
278 repo = None
279 if report or run_context() is not None:
280 from livery.workshop._forge_lane import this_repository
282 repo = this_repository(root)
283 verify_flow(
284 root,
285 package,
286 python=python or f"{sys.version_info.major}.{sys.version_info.minor}",
287 registry=registry,
288 index=target.url,
289 extras=extras,
290 repo=repo,
291 )
294@release.task(name="driver", hidden=True)
295def release_driver(
296 workshop: Annotated[
297 str,
298 doc(
299 "a released livery-workshop version to drive the wave; empty keeps"
300 " the checkout's"
301 ),
302 ] = "",
303) -> None:
304 """Install the released workshop *workshop* names over the checkout's own.
306 The wave's recovery for a run whose own workshop was the fault: a
307 re-dispatch names a released driver, and this step installs it
308 before the wave's verbs run, so they run under it. Empty, the
309 checkout's workshop drives the wave and nothing is installed; a
310 re-run then does what the first run did.
311 """
312 import livery.toolroom.tools as tools
314 if not workshop:
315 print(" driver: the checkout's own workshop drives the wave")
316 return
317 from livery.workshop._ci_generate import DRIVER_DIST
319 tools.uv("pip", "install", f"{DRIVER_DIST}=={workshop}")
320 print(f" driver: {DRIVER_DIST} {workshop} installed over the checkout's")