Coverage for packages/workshop/src/livery/workshop/_release_driver.py: 87%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""``workflow.release``: the release train's driver on the engine.
2
3One release shape for a set of N >= 1 packages: derive each member's
4version from its commits and its entry through the release notes'
5provider, bump floors within the set only, stamp, commit per member in
6dependency order, and hand the branch to the shared engine. The branch
7decides the act: main-family (``main`` and the engine's ``workflow/``
8namespace) runs the real train, any other branch is the dev act, a wheel
9straight from the branch. ``--local`` is everything that stays on this
10machine: derive, build, validate, report, then roll the stamps back like
11a failed prepare, leaving ``dist/`` and the report.
12"""
13
14from __future__ import annotations
15
16import contextlib
17import time
18from collections.abc import Callable, Sequence
19from dataclasses import dataclass
20from functools import partial
21from pathlib import Path
22from typing import Annotated
23
24import livery.footman as footman
25from livery import git
26from livery.footman import doc, fail
27from livery.forge import ForgeError, Repository, Run
28from livery.workshop import _lifecycle
29from livery.workshop._graph import order_topologically
30from livery.workshop._packages import Package, discover_packages, receipt_member
31from livery.workshop._release import prepare_release
32from livery.workshop._verdict import (
33 FollowTimedOut,
34 ForgeUnreachable,
35 Pending,
36 Transient,
37 follow,
38)
39from livery.workshop._versions import derive_version
40from livery.workshop._workflow_engine import Submission, run_workflow
41from livery.workshop._workflow_state import WorkflowKind
42from livery.workshop._workflow_tasks import workflow
43
44#: The base gate's patience and cadence.
45BASE_TIMEOUT = 30 * 60
46BASE_POLL = 15
47#: A tip with zero reported contexts this long gets one nudge: run
48#: creation itself failed, and patience cannot fix that.
49SILENT_NUDGE_AFTER = 3 * 60
50
51
52@dataclass(frozen=True)
53class MemberPlan:
54 """One member's derived release: the package and its next version."""
55
56 package: Package
57 version: str
58
59
60#: The longest the members' joined directories may run in a release's
61#: name. The name is a branch, and a checkout keeps a branch as a file
62#: under ``.git/refs/remotes/origin/``: past Windows' path limit there,
63#: a CI checkout fails before anything runs.
64NAME_LIMIT = 64
65
66
67def release_name(members: tuple[str, ...]) -> str:
68 """The workflow name a set earns: its directories, sorted and ``+``-joined.
69
70 A set whose joined directories run past `NAME_LIMIT` is named by
71 its size and a digest of them instead, so the branch stays short
72 and the same set always earns the same name.
73 """
74 joined = "+".join(sorted(members))
75 if len(joined) <= NAME_LIMIT:
76 return f"release/{joined}"
77 import hashlib
78
79 digest = hashlib.sha256(joined.encode("utf-8")).hexdigest()[:12]
80 return f"release/{len(members)}-packages-{digest}"
81
82
83def resolve_set(root: Path, paths: tuple[str, ...]) -> tuple[Package, ...]:
84 """The named packages, in dependency order; every name must exist."""
85 packages = {p.path: p for p in discover_packages(root)}
86 chosen: list[Package] = []
87 for path in paths:
88 package = packages.get(path) or packages.get(f"packages/{path}")
89 if package is None:
90 known = ", ".join(sorted(packages))
91 fail(f"{path} is not a workspace package; members: {known}")
92 chosen.append(package)
93 return order_topologically(tuple(chosen))
94
95
96def derive_plans(root: Path, members: tuple[Package, ...]) -> tuple[MemberPlan, ...]:
97 """Each member's next version, every member refused when unchanged.
98
99 Runs before the branch is cut, from read-only state: a refusal
100 here has nothing to undo. A member whose bump equals its newest
101 released tag has nothing unreleased, and minting a number the
102 index already has is refused with the options. The tag is the
103 judge, never the stamped version: a stamp can land without its
104 release cutting, and judging by it would strand that release
105 (the same rule livery.workshop._release.prepare_release keeps).
106 """
107 from livery.workshop._release import _last_released
108
109 plans: list[MemberPlan] = []
110 unchanged: list[str] = []
111 for package in members:
112 released = _last_released(root, package)
113 derived = derive_version(root, package, released=released)
114 if not derived or derived == released:
115 unchanged.append(package.member)
116 continue
117 plans.append(MemberPlan(package=package, version=derived))
118 if unchanged:
119 names = ", ".join(unchanged)
120 fail(
121 f"nothing unreleased touches: {names}. Options: drop them from"
122 " the set (release the rest now); or, if a hollow re-release is"
123 " truly meant, stamp a version explicitly with"
124 f" `{footman.prog()} release.prepare <path> <version>`."
125 )
126 return tuple(plans)
127
128
129def _write_manifest(
130 root: Path, plans: tuple[MemberPlan, ...], *, mined_at: str
131) -> None:
132 """Write the release set's record for the squash's discovery.
133
134 The publish wave and the title check read it at the ref, so a
135 recovery re-prepare whose stamps already sit on the base still
136 names every member; see [livery.workshop._publish.MANIFEST][].
137 The record carries *mined_at*, which differs for every prepare,
138 so every release squash touches the file: the dispatch finds the
139 squash as the last commit touching it, and a prepare that takes
140 over an abandoned squash at the same versions still has a commit.
141 """
142 import json
143
144 from livery.workshop._publish import MANIFEST
145
146 payload = {
147 "schema": 1,
148 "mined-at": mined_at,
149 "members": [
150 {
151 "dir": plan.package.member,
152 "name": plan.package.name,
153 "version": plan.version,
154 }
155 for plan in plans
156 ],
157 }
158 (root / MANIFEST).write_text(json.dumps(payload, indent=1) + "\n", encoding="utf-8")
159
160
161def member_pairs_at(root: Path, ref: str) -> list[tuple[str, str]] | None:
162 """(distribution, version) for each member in the member list at *ref*.
163
164 Each name is read from the member's contract as committed at
165 *ref*, so the answer describes that commit alone. None when *ref*
166 carries no readable list.
167 """
168 import tomllib
169
170 from livery.workshop._publish import MANIFEST, read_manifest
171
172 recorded = read_manifest(git.file_at(root, ref, MANIFEST))
173 if recorded is None:
174 return None
175 pairs: list[tuple[str, str]] = []
176 for directory, version in recorded:
177 try:
178 contract = tomllib.loads(
179 git.file_at(root, ref, f"packages/{directory}/workshop.toml")
180 )
181 name = str(contract.get("name") or directory)
182 except tomllib.TOMLDecodeError:
183 name = directory
184 pairs.append((name, version))
185 return pairs
186
187
188def bump_set_floors(root: Path, plans: tuple[MemberPlan, ...]) -> list[str]:
189 """Raise floors between co-released members through the stamp phase; the files.
190
191 Within the set only (contract: a solo release never moves a
192 floor): each member's stamp phase runs at the version it declares
193 now, with every other member's version as its floors, so the
194 version stays for `prepare_release` to stamp. Each step raises the
195 floors in its own manifests, and the base those of the member's
196 ``[[depends]]`` edges, as `livery.workshop._lifecycle.stamp` says.
197 The files are the ones the phase reported, relative to *root*.
198 """
199 if len(plans) < 2:
200 return []
201 changed: list[str] = []
202 for plan in plans:
203 package = plan.package
204 floors = {
205 other.package.path: other.version
206 for other in plans
207 if other.package.path != package.path
208 }
209 current = _lifecycle.current_version(package)
210 stamped = _lifecycle.stamp(package, root, current, floors=floors)
211 changed += [
212 (package.directory / name).relative_to(root).as_posix() for name in stamped
213 ]
214 return changed
215
216
217def rollback_prepare(
218 root: Path, members: tuple[Package, ...], reported: Sequence[str] = ()
219) -> None:
220 """Restore exactly the files prepare writes; never raises.
221
222 The error being unwound is the one worth seeing, so this raises
223 nothing of its own: each member's changelog, contract and version
224 files return to HEAD, and so do the files the stamp phase
225 *reported* raising floors in (relative to *root*), the set's
226 manifest and the workspace lock the stamp refreshed. One of these
227 files on disk that HEAD lacks is one prepare created, as a first
228 release's changelog and manifest are, and it is removed, so the
229 switch back to the base does not carry it along. Each restore reads
230 HEAD, never the index: a commit that failed (a signing agent that
231 refused) has already staged every change, and a restore from the
232 index would keep them. Each path the rollback could not put back is
233 printed with the reason, and the other paths are put back all the
234 same.
235 """
236 for path, reason in _put_back(root, _prepare_paths(root, members, reported)):
237 print(f" the rollback could not restore {path}: {reason}")
238
239
240def _prepare_paths(
241 root: Path, members: tuple[Package, ...], reported: Sequence[str] = ()
242) -> tuple[str, ...]:
243 """The paths prepare may write for *members*, each once, from *root*.
244
245 The files the stamp phase *reported* raising floors in, then each
246 member's changelog, its contract and the files its set's stamp
247 writes a version into, then the workspace lock and the set's
248 manifest, with forward slashes. The rollback puts back exactly
249 these, and the local act refuses while one of them has changes of
250 its own, so the two read the same list.
251 """
252 from livery.workshop._contract import CONTRACT
253 from livery.workshop._publish import MANIFEST
254
255 paths = [Path(name).as_posix() for name in reported]
256 for package in members:
257 base = package.directory.relative_to(root)
258 paths.extend((base / name).as_posix() for name in ("CHANGELOG.md", CONTRACT))
259 # Every file the set's stamp writes a version into. A set that
260 # cannot name them restores the rest regardless.
261 with contextlib.suppress(Exception):
262 paths.extend(
263 home.relative_to(root).as_posix()
264 for home in _lifecycle.version_files(package)
265 )
266 paths.extend(("uv.lock", MANIFEST))
267 return tuple(dict.fromkeys(paths))
268
269
270def _require_unchanged(root: Path, members: tuple[Package, ...]) -> None:
271 """Refuse while a path prepare may write has changes of its own, naming each.
272
273 The rollback returns each of those paths to HEAD and deletes one
274 HEAD lacks, so an uncommitted edit there, or a file a person made
275 there by hand, would be lost. A change anywhere else in the tree
276 does not refuse.
277
278 Raises:
279 Failed: naming each such path, modified, staged, deleted or
280 untracked, and saying to commit or stash it first.
281 """
282 out = git.run(
283 root,
284 "status",
285 "--porcelain",
286 "-z",
287 "--untracked-files=all",
288 "--",
289 *_prepare_paths(root, members),
290 )
291 fields = out.split("\0")
292 changed: list[str] = []
293 index = 0
294 while index < len(fields):
295 record = fields[index]
296 index += 1
297 if len(record) < 4:
298 continue
299 changed.append(record[3:])
300 if record[0] in "RC":300 ↛ 302line 300 didn't jump to line 302 because the condition on line 300 was never true
301 # A rename or a copy names the path it came from next.
302 index += 1
303 if changed:
304 listed = "".join(f"\n {path}" for path in sorted(set(changed)))
305 fail(
306 "the local act writes these files and then restores them from"
307 f" HEAD, so the changes they have now would be lost:{listed}\n"
308 "Commit or stash them first, then run it again."
309 )
310
311
312def _put_back(root: Path, paths: tuple[str, ...]) -> list[tuple[str, str]]:
313 """Return each of *paths* to HEAD; each path that failed, with the reason.
314
315 A path HEAD has is checked out from HEAD. A path HEAD lacks that
316 is on disk is taken out of the index and deleted. A path in
317 neither is left alone. The paths HEAD has are checked out in one
318 call, and only when git refuses that call is each checked out
319 alone: git refuses the whole call for one bad path, so the one
320 path git refuses never stops the rest.
321 """
322 tracked: list[str] = []
323 failed: list[tuple[str, str]] = []
324 for path in paths:
325 try:
326 if git.tracks(root, f"HEAD:{path}"):
327 tracked.append(path)
328 elif (root / path).is_file():
329 git.unstage(root, path)
330 (root / path).unlink()
331 except (git.GitError, OSError) as error:
332 failed.append((path, str(error)))
333 if tracked and git.restore(root, *tracked):
334 for path in tracked:
335 refused = git.restore(root, path)
336 if refused:
337 failed.append((path, refused))
338 return failed
339
340
341def verify_set(root: Path, plans: tuple[MemberPlan, ...]) -> None:
342 """Run the publish job's own checks over the stamped set, before any leg.
343
344 The wave refuses a member whose version homes disagree with its tag,
345 whose release notes are unsound, or whose floor names an unreleased
346 version, and it refuses only after the release has merged. The same
347 checks on the stamped tree refuse before a release pull request
348 exists. The set's own tags count as released, as the wave counts them.
349
350 Raises:
351 Failed: as the publish job's check refuses, naming the member and
352 each problem.
353 """
354 from livery.workshop._release import verify_release
355
356 coreleased = frozenset(f"{plan.package.path}/v{plan.version}" for plan in plans)
357 for plan in plans:
358 verify_release(
359 root, f"{plan.package.path}/v{plan.version}", coreleased=coreleased
360 )
361
362
363def _wheel_dists(plans: tuple[MemberPlan, ...]) -> tuple[Path, ...]:
364 """The find-links dirs: each member's ``dist/`` that exists, in set order.
365
366 Read after the set's builds. A build that writes nothing there, a
367 conan member's, leaves no directory to name, and a find-links path
368 that does not exist fails the sibling legs outright.
369 """
370 dists = (plan.package.directory / "dist" for plan in plans)
371 return tuple(dist for dist in dists if dist.is_dir())
372
373
374#: The key of `[release]` listing the resolutions a release tests at.
375PROVE = "prove"
376
377#: The resolutions a release may test a member at, in the order the legs
378#: run: the floor first, since a floor lying about compatibility fails
379#: before anything else is spent, then the newest, then the lock's.
380RESOLUTIONS = ("floor", "latest", "head")
381
382#: The resolutions a release tests at when no contract lists any.
383DEFAULT_RESOLUTIONS = ("floor", "latest")
384
385
386def proved_resolutions(root: Path, package: Package) -> tuple[tuple[str, ...], str]:
387 """The resolutions *package*'s release tests at, and the file that listed them.
388
389 The package's own `[release] prove` wins; the workspace's is the
390 default; without either the release tests at
391 [livery.workshop._release_driver.DEFAULT_RESOLUTIONS][], and the
392 file is empty. The contract's judge refuses a word other than the
393 three and a word listed twice, so the list holds each at most
394 once, in the order the legs run.
395 """
396 from livery.workshop._contract import load_contract
397
398 for contract in (package.directory / "workshop.toml", root / "workshop.toml"):
399 if not contract.is_file():399 ↛ 400line 399 didn't jump to line 400 because the condition on line 399 was never true
400 continue
401 release = load_contract(contract).get("release") or {}
402 if PROVE in release:
403 listed = {str(word) for word in release[PROVE]}
404 where = contract.relative_to(root).as_posix()
405 return tuple(word for word in RESOLUTIONS if word in listed), where
406 return DEFAULT_RESOLUTIONS, ""
407
408
409def validate_member(
410 root: Path, plan: MemberPlan, release_dirs: tuple[Path, ...]
411) -> None:
412 """Run the member's test phase isolated once per resolution it proves; report each.
413
414 One leg per resolution
415 ([livery.workshop._release_driver.proved_resolutions][]), in the
416 order of [livery.workshop._release_driver.RESOLUTIONS][], so the
417 floor leg runs before the latest leg; a list from a contract is
418 named with its file. The report names what each leg resolved per
419 co-member and sibling: every workspace member but the one under
420 test. The caller builds every set member's wheel first: the legs'
421 find-links name each sibling's ``dist/``, so a later member's
422 wheel must exist before an earlier member's floor leg resolves.
423
424 A member whose extensions add no isolated test, as a conan
425 package's do, has no venv to isolate: its own gate already built
426 and ran ctest, so the legs skip saying why.
427 """
428 if not _lifecycle.has_isolated_test(plan.package):
429 print(
430 f" {plan.package.name}: isolated legs skip (its extensions add no"
431 " isolated test, since it publishes no wheel; its own gate builds"
432 " and tests)"
433 )
434 return
435 legs, where = proved_resolutions(root, plan.package)
436 if where:
437 listed = ", ".join(legs) or "nothing, so no leg runs"
438 print(f" {plan.package.name}: [release] {PROVE} in {where} lists {listed}")
439 members = {_normalised(package.name) for package in discover_packages(root)}
440 own = _normalised(plan.package.name)
441 for leg in legs:
442 resolved = _lifecycle.isolated_test(
443 plan.package, root, resolution=leg, release_dirs=release_dirs
444 )
445 siblings = {
446 name: version
447 for name, version in sorted(resolved.items())
448 if _normalised(name) in members and _normalised(name) != own
449 }
450 listed = ", ".join(f"{n} {v}" for n, v in siblings.items()) or "no siblings"
451 print(f" {plan.package.name} {leg} leg: {listed}")
452
453
454def _normalised(name: str) -> str:
455 """A distribution's name as an index compares it: lower case, hyphens."""
456 return name.lower().replace("_", "-").replace(".", "-")
457
458
459def _base_tree_verified(root: Path, base: str) -> bool:
460 """Whether the verified record already vouches for *base*'s tip tree.
461
462 A gate that proved this exact tree green in full, on the pull
463 request whose squash became the tip, lets the release start at
464 once instead of waiting for the tip's own push run. Anything the
465 record cannot decide says why, answers False, and the wait proceeds.
466 """
467 from livery.workshop import _verified
468
469 try:
470 git.fetch(root)
471 sha = git.remote_head(root, base)
472 tree = _verified.tree_id(root, sha) if sha else ""
473 except Exception as error:
474 print(
475 f" {base}: its tip cannot be read for the verified record: {error};"
476 " waiting for the tip's own run"
477 )
478 return False
479 if not tree:479 ↛ 480line 479 didn't jump to line 480 because the condition on line 479 was never true
480 print(f" {base}: no tree at origin's tip to verify; waiting for its run")
481 return False
482 found, why = _verified.record(root, tree)
483 if found is None:
484 if why:484 ↛ 485line 484 didn't jump to line 485 because the condition on line 484 was never true
485 print(f" {base}: tree {tree[:12]}: {why}; waiting for the tip's own run")
486 return False
487 if found.scope != _verified.FULL:
488 print(
489 f" {base}: tree {tree[:12]} was proved at scope {found.scope}, not"
490 " full; waiting for the tip's own run"
491 )
492 return False
493 print(
494 f" {base} verified: tree {tree[:12]} proved green by run {found.run};"
495 " the release starts now"
496 )
497 return True
498
499
500def require_verified_base(
501 repo: Repository,
502 root: Path,
503 base: str,
504 *,
505 force: bool = False,
506 timeout: float = BASE_TIMEOUT,
507 poll: float = BASE_POLL,
508) -> None:
509 """Wait for the base's own push CI to be green; stop on red or skip.
510
511 Branch protection only ever judged PR heads, and a release
512 publishes the base's tree, so the base's push run is the only
513 vouching there is. Green, not merely not-red; red is a verdict
514 waiting cannot improve; a skip-ci tip will never get a run; an
515 unreachable forge fails open, the engine's UNKNOWN story says it
516 better.
517
518 Zero reported contexts after minutes means run creation itself
519 failed, and every forge can do it: Gitea's actions queue could
520 wedge before 1.27.3, GitHub silently drops a push's workflow-run
521 creation under load, and GitLab can never mint the pipeline (a
522 job-queue backlog, or workflow rules evaluating to nothing). The
523 combined-status read
524 reports all three identically, so detection is uniform; the safe
525 remedy is not (whether a tool may push to the base varies per
526 forge and protection), so the silent tip gets a printed teaching
527 naming the fresh-push-event remedy, never an automatic push. The
528 timeout tells the two conditions apart: a run that reported and
529 hung sends the reader to the runners, a tip that never got a run
530 names run creation.
531 """
532 if force:
533 print(" base verification skipped (--force-unverified-base)")
534 return
535 if _base_tree_verified(root, base):
536 return
537 announced = False
538 silent_since: float | None = None
539 nudged = False
540 ever_reported = False
541
542 def read() -> bool | Pending:
543 nonlocal announced, silent_since, nudged, ever_reported
544 try:
545 git.fetch(root)
546 sha = git.remote_head(root, base)
547 status = repo.checks.status(sha) if sha else None
548 except ForgeError:
549 raise
550 except Exception as error:
551 # The base gate fails open: a tree nobody can vouch for
552 # releases, and the reason is said rather than swallowed.
553 print(f" {base}'s CI could not be read ({error}); releasing unverified")
554 return True
555 if status is None or status.state == "success":
556 return True
557 if status.state == "failure":
558 fail(
559 f"{base}'s own CI is red, and a release publishes that tree."
560 f" Fix {base} first (`{footman.prog()} ci.logs` on it names"
561 " the job), or"
562 " release with --force-unverified-base if you accept an"
563 " unvouched tree."
564 )
565 if "[skip ci]" in git.commit_message(root, sha):565 ↛ 566line 565 didn't jump to line 566 because the condition on line 565 was never true
566 fail(
567 f"{base}'s tip carries a skip-ci marker, so CI will never"
568 " report on it. Push a commit CI can run, or"
569 " --force-unverified-base to accept it unverified."
570 )
571 now = time.monotonic()
572 if status.contexts:
573 ever_reported = True
574 silent_since = None
575 elif silent_since is None:
576 silent_since = now
577 elif not nudged and now - silent_since >= SILENT_NUDGE_AFTER:577 ↛ 578line 577 didn't jump to line 578 because the condition on line 577 was never true
578 nudged = True
579 print(
580 f" {base}'s tip has had no CI run for"
581 f" {SILENT_NUDGE_AFTER // 60} min; a fresh push event may be"
582 " needed (an empty commit mints one)."
583 )
584 if not announced:
585 announced = True
586 print(
587 f" waiting for {base}'s own CI before releasing (up to"
588 f" {BASE_TIMEOUT // 60} min)"
589 )
590 return Pending()
591
592 try:
593 follow(
594 repo,
595 read,
596 subject=f"{base}'s own CI",
597 interval=poll,
598 timeout=timeout,
599 quiet=None,
600 )
601 except ForgeUnreachable as exc:
602 print(exc.line)
603 print(f" releasing unverified: {base}'s CI could not be read")
604 except FollowTimedOut:
605 # Not started and hanging are different problems with
606 # different remedies, so the timeout names the one that
607 # actually happened.
608 if ever_reported:
609 fail(
610 f"{base} reported a run but never went green within"
611 f" {timeout / 60:.0f} minutes. Check the runners"
612 f" (`{footman.prog()} status --watch` on a branch follows"
613 " a run), or"
614 " --force-unverified-base."
615 )
616 fail(
617 f"{base}'s tip never got a CI run in {timeout / 60:.0f}"
618 " minutes: run creation itself failed, and waiting cannot"
619 " fix that. A fresh push event mints a run (an empty"
620 " commit, or its PR merged), or --force-unverified-base."
621 )
622
623
624class ReleaseDriver:
625 """The release kind's driver for the shared engine."""
626
627 kind = WorkflowKind.RELEASE
628
629 def __init__(
630 self,
631 root: Path,
632 repo: Repository,
633 members: tuple[Package, ...],
634 *,
635 armed: bool,
636 force_unverified_base: bool = False,
637 wave_timeout: float = 1800.0,
638 ) -> None:
639 self._root = root
640 self._repo = repo
641 self._members = members
642 self.members = tuple(p.member for p in members)
643 self.name = release_name(self.members)
644 self.armed = armed
645 self._force = force_unverified_base
646 self._wave_timeout = wave_timeout
647 # An armed release follows its pull request for as long as it
648 # would wait for the wave; the engine's own tests pass zero.
649 self.watch = wave_timeout
650 # Set by `discard`: the next prepare starts from the base, and
651 # the given-up branch's manifest says which members' legs
652 # still hold.
653 self._fresh = False
654 self._previous: tuple[str, tuple[tuple[str, str], ...]] | None = None
655
656 @property
657 def branch(self) -> str:
658 return f"workflow/{self.name}"
659
660 @property
661 def base(self) -> str:
662 return "main"
663
664 def discard(self) -> None:
665 """Give up the prepared branch: the base moved in the set's paths.
666
667 The next prepare derives the set again from the base and
668 force-pushes the branch, so the open pull request carries the
669 new stamps, entries and ``Mined-At``. The given-up branch's
670 manifest is kept: a member whose directory the base did not
671 move since that prepare, at the same versions for the whole
672 set, keeps its legs' verdict instead of running them again.
673 """
674 import json
675
676 from livery.workshop._publish import MANIFEST, read_manifest
677
678 root = self._root
679 git.fetch(root)
680 text = git.file_at(root, f"origin/{self.branch}", MANIFEST)
681 pairs = read_manifest(text) if text else None
682 mined = ""
683 if pairs:683 ↛ 686line 683 didn't jump to line 686 because the condition on line 683 was always true
684 with contextlib.suppress(ValueError, TypeError, AttributeError):
685 mined = str(json.loads(text).get("mined-at") or "")
686 self._previous = (mined, pairs) if pairs and mined else None
687 if git.current_branch(root) == self.branch:687 ↛ 689line 687 didn't jump to line 689 because the condition on line 687 was always true
688 git.switch(root, self.base)
689 if git.local_branch_exists(root, self.branch):689 ↛ 691line 689 didn't jump to line 691 because the condition on line 689 was always true
690 git.delete_branch(root, self.branch)
691 self._fresh = True
692
693 def legs_kept(self, plans: tuple[MemberPlan, ...], mined_at: str) -> set[str]:
694 """The members whose legs from the discarded prepare still hold.
695
696 Only when the whole set keeps its versions (a co-member's new
697 version moves the floors every other member is tested at), and
698 then each member the base did not touch between the two mining
699 points.
700 """
701 if self._previous is None:
702 return set()
703 previous_mined, previous_pairs = self._previous
704 now = tuple((plan.package.member, plan.version) for plan in plans)
705 if tuple(sorted(previous_pairs)) != tuple(sorted(now)):
706 return set()
707 kept: set[str] = set()
708 for plan in plans:
709 try:
710 moved = git.log_paths(
711 self._root, f"{previous_mined}..{mined_at}", (plan.package.path,)
712 )
713 except git.GitError:
714 continue # an unreadable span proves nothing: run the legs
715 if not moved:
716 kept.add(plan.package.member)
717 return kept
718
719 def prepare(self) -> Submission | None:
720 """Derive, stamp, and commit the set; recover an existing branch.
721
722 A branch already alive locally or on the remote is recovery:
723 nothing is rebuilt, the engine re-submits what the branch
724 holds, and titles come from the ref, never the working tree.
725 """
726 root = self._root
727 if not self._fresh and (
728 git.local_branch_exists(root, self.branch)
729 or self._repo.branch_exists(self.branch)
730 ):
731 if git.current_branch(root) != self.branch:731 ↛ 732line 731 didn't jump to line 732 because the condition on line 731 was never true
732 if not git.local_branch_exists(root, self.branch):
733 git.fetch(root)
734 git.run(
735 root, "checkout", "-b", self.branch, f"origin/{self.branch}"
736 )
737 else:
738 git.switch(root, self.branch)
739 print(f" recovering the prepared {self.name} from its branch")
740 self._require_fresh_base()
741 return self._submission_from_ref()
742
743 require_verified_base(self._repo, root, self.base, force=self._force)
744 plans = derive_plans(self._root, self._members)
745 mined_at = git.head_sha(root)
746 kept = self.legs_kept(plans, mined_at)
747 git.create_branch(root, self.branch)
748 prepared = False
749 floor_changes: list[str] = []
750 try:
751 floor_changes = bump_set_floors(self._root, plans)
752 if floor_changes:
753 print(f" floors raised within the set: {', '.join(floor_changes)}")
754 _write_manifest(self._root, plans, mined_at=mined_at)
755 for plan in plans:
756 prepare_release(self._root, plan.package.path, plan.version)
757 _lifecycle.build_release(plan.package, self._root)
758 if git.is_clean(root):758 ↛ 763line 758 didn't jump to line 763 because the condition on line 758 was never true
759 # Already stamped: a release squash-merged but never
760 # published leaves main carrying exactly these
761 # entries and versions, and re-preparing is the
762 # recovery. A clean tree is that state, not a fault.
763 print(
764 f" {plan.package.name} v{plan.version}:"
765 " already stamped on the base; nothing to commit"
766 )
767 continue
768 git.commit_all(
769 root, f"chore(release): {plan.package.name} v{plan.version}"
770 )
771 if not git.is_clean(root):771 ↛ 776line 771 didn't jump to line 776 because the condition on line 771 was never true
772 # Only the manifest changed: every member was already
773 # stamped on the base (a merged release whose publish
774 # failed), and the manifest alone is what lets the
775 # squash's discovery still name the whole set.
776 git.commit_all(root, "chore(release): the set manifest")
777 verify_set(self._root, plans)
778 # Every member's wheel exists before any leg runs; a
779 # failed leg still tears the whole branch down, commits
780 # included, so nothing unvalidated survives.
781 release_dirs = _wheel_dists(plans)
782 for plan in plans:
783 if plan.package.member in kept:783 ↛ 784line 783 didn't jump to line 784 because the condition on line 783 was never true
784 print(
785 f" {plan.package.name} v{plan.version}: legs kept from the"
786 " discarded prepare; the base did not move its directory"
787 )
788 continue
789 validate_member(self._root, plan, release_dirs)
790 prepared = True
791 finally:
792 if not prepared:
793 rollback_prepare(self._root, self._members, floor_changes)
794 git.switch(root, self.base)
795 git.delete_branch(root, self.branch)
796 title = release_title([(plan.package.name, plan.version) for plan in plans])
797 body = (
798 "## Release summary\n"
799 + "\n".join(f"- **{plan.package.name}** v{plan.version}" for plan in plans)
800 + f"\n\nMined-At: {mined_at}"
801 )
802 return Submission(title=title, body=body)
803
804 def _require_fresh_base(self) -> None:
805 """Refuse a prepared branch whose base moved under it.
806
807 hse merges the default branch into a stale release branch and
808 re-verifies; livery's entries carry a mining point instead,
809 and commits merged in beneath it would ship under-documented,
810 so the stale branch is refused outright: abandon and re-run,
811 and the fresh prepare mines everything. Deviation from hse
812 ruled 2026-09-04 with issue #161.
813 """
814 root = self._root
815 git.fetch(root)
816 base_sha = git.run(root, "rev-parse", f"origin/{self.base}").strip()
817 if git.is_ancestor(root, base_sha, "HEAD"):
818 return
819 fail(
820 f"{self.base} has moved past this prepared release: commits"
821 " it gained are not mined into the branch's entries, and"
822 " releasing them under-documented is worse than re-preparing."
823 f"\n Run `{footman.prog()} abandon` on the branch, then"
824 f" `{footman.prog()} workflow.release` again."
825 )
826
827 def _submission_from_ref(self) -> Submission:
828 """The title and body the branch's member list states.
829
830 Recovery reads the branch's committed member list, never the
831 working tree and never commit subjects: a checkout standing
832 elsewhere holds a different tree, and a rider commit is not
833 part of what was prepared, so the rebuilt title stays
834 consistent with the content the squash will carry.
835 """
836 root = self._root
837 mined_at = git.run(root, "merge-base", "HEAD", f"origin/{self.base}").strip()
838 pairs = member_pairs_at(root, "HEAD") or []
839 body = (
840 "## Release summary\n"
841 + "\n".join(f"- **{name}** v{version}" for name, version in pairs)
842 + f"\n\nMined-At: {mined_at}"
843 )
844 return Submission(title=release_title(pairs), body=body)
845
846 def on_merged(self) -> None:
847 """The merge point dispatches the wave; follow it to its verdict.
848
849 The wave's run is awaited by its id, then followed the way
850 ``ci.status --point=release --wait`` follows it, so the act
851 ends with the wave's own verdict and exit; the receipt tags
852 say when each member is done. A wave timeout of zero reports
853 the merge and names the dispatch verb as the confirmation
854 instead of waiting: the engine's own tests run against a
855 forge with no merge point.
856 """
857 if self._wave_timeout <= 0:
858 print(
859 " merged; the merge point dispatches the wave, confirm it with"
860 f" `{footman.prog()} workflow.release.dispatch`"
861 )
862 return
863 transient = Transient(interval=_WAVE_POLL)
864 before = {run.id for run in _wave_runs_answered(self._repo, transient)}
865 run_id = await_wave(
866 self._repo,
867 before=before,
868 timeout=self._wave_timeout,
869 transient=transient,
870 )
871 if run_id is None:871 ↛ 872line 871 didn't jump to line 872 because the condition on line 871 was never true
872 fail(
873 "merged, but no release wave appeared within"
874 f" {self._wave_timeout:.0f}s: the merge point's dispatch job"
875 " runs after main's own verdict, so a red main or a slow"
876 " queue is the usual cause. The recovery is"
877 f" `{footman.prog()} workflow.release.dispatch` from any"
878 " checkout, which answers green once the wave is up."
879 )
880 print(
881 f" merged; the merge point dispatched the wave, run {run_id}; the"
882 " receipt tags say when each member is done"
883 )
884 run = next(
885 (r for r in _wave_runs_answered(self._repo, transient) if r.id == run_id),
886 None,
887 )
888 if run is None:888 ↛ 889line 888 didn't jump to line 889 because the condition on line 888 was never true
889 return
890 from livery.workshop._ci_tasks import follow_run
891
892 code = follow_run(self._repo, "release", run, timeout=self._wave_timeout)
893 self._trace_the_chain()
894 if code:
895 raise SystemExit(code)
896
897 def _trace_the_chain(self) -> None:
898 """Fold everything this release caused into the command's own trace.
899
900 A release is two commits and one hop. The branch commit carries
901 the pull request's run, and the commit its merge made carries
902 the base's own run and the wave dispatched at it. One walk from
903 the branch holds the whole story, and a red wave's is the one
904 most worth having, so this runs before the exit code does.
905
906 The branch is already gone from a checkout that recovered a
907 release it did not prepare, and then the release squash on the
908 base is where the walk starts instead.
909 """
910 from livery.workshop._traces import drop_chain
911
912 root = self._root
913 at = git.sha_of(root, self.branch)
914 if not at:914 ↛ 916line 914 didn't jump to line 916 because the condition on line 914 was always true
915 at, _subject = newest_release_squash(root, self.base)
916 if line := drop_chain(self._repo, root, commit=at):
917 print(f" {line}")
918
919
920#: The longest release title. GitHub's auto-merge refuses a squash
921#: headline it judges too long, and its refusal names 80 characters.
922TITLE_LIMIT = 80
923
924
925def release_title(pairs: Sequence[tuple[str, str]]) -> str:
926 """The release pull request's title: each member with its version, or a count.
927
928 The title is the squash commit's headline, and arming hands it to
929 GitHub's auto-merge, which refuses a long one. A set whose title
930 would pass `TITLE_LIMIT` characters is counted instead; the pull
931 request's body and the commit's body list every member.
932 """
933 listed = ", ".join(f"{name} v{version}" for name, version in pairs)
934 title = f"chore(release): released {listed}"
935 if len(title) <= TITLE_LIMIT:
936 return title
937 counted = "1 package" if len(pairs) == 1 else f"{len(pairs)} packages"
938 return f"chore(release): released {counted}"
939
940
941def runs_the_train(branch: str) -> bool:
942 """Whether `workflow.release` on *branch* is the release train, not the dev act.
943
944 ``main`` and the engine's reserved ``workflow/`` branches release;
945 any other branch builds a dev wheel straight from its commit.
946 """
947 return branch == "main" or branch.startswith("workflow/")
948
949
950def fresh_receipts(root: Path) -> None:
951 """Fetch origin's tags, so a derivation reads every receipt a wave cut.
952
953 A release wave tags its receipts on the remote, and this checkout
954 holds them only after a fetch: a derivation from stale tags names
955 versions the index already has. A checkout with no origin has only
956 its own tags to read; one that cannot reach origin derives from its
957 own and says so.
958 """
959 if not git.has_remote(root, "origin"):959 ↛ 960line 959 didn't jump to line 960 because the condition on line 959 was never true
960 return
961 try:
962 git.fetch_tags(root)
963 except git.GitError as error:
964 print(
965 " origin could not be fetched, so the versions come from this"
966 f" checkout's own tags: {error}"
967 )
968
969
970def local_release(root: Path, members: tuple[Package, ...]) -> None:
971 """Everything that stays on this machine, then the stamps roll back.
972
973 Derive, stamp (so the built wheels carry the would-be versions),
974 build, run the isolated legs, print the would-be release, restore
975 the tree; ``dist/`` and the report remain. Publishing consent is
976 never asked because nothing leaves the machine. The derivation
977 reads origin's receipts, fetched first, so it names the versions
978 the armed act would ([livery.workshop._release_driver.fresh_receipts][]).
979 Before any of it, the act refuses while a file it would write has
980 changes of its own, since the restore would discard them; a change
981 anywhere else in the tree is left alone.
982 """
983 _require_unchanged(root, members)
984 fresh_receipts(root)
985 plans = derive_plans(root, members)
986 print(" act: local; nothing leaves this machine")
987 floor_changes: list[str] = []
988 try:
989 floor_changes = bump_set_floors(root, plans)
990 for plan in plans:
991 prepare_release(root, plan.package.path, plan.version)
992 _lifecycle.build_release(plan.package, root)
993 verify_set(root, plans)
994 release_dirs = _wheel_dists(plans)
995 for plan in plans:
996 validate_member(root, plan, release_dirs)
997 listed = ", ".join(f"{plan.package.name} v{plan.version}" for plan in plans)
998 print(f" would release: {listed}")
999 print(" wheels in each member's dist/; the tree is restored")
1000 finally:
1001 rollback_prepare(root, members, floor_changes)
1002
1003
1004#: The release workflow, as the forges address one for a dispatch and
1005#: name one on a run (GitHub lists the path, Gitea the file; the
1006#: basename is the comparison).
1007RELEASE_WORKFLOW = "release.yml"
1008
1009
1010def _wave_runs(repo: Repository) -> tuple[Run, ...]:
1011 """The release workflow's newest dispatched runs, newest first.
1012
1013 Asked of the workflow's own listing, so every poll of a wave reads
1014 one page whatever else was dispatched.
1015 """
1016 from livery.workshop._ci_tasks import RECENT_RUNS
1017
1018 return tuple(
1019 run
1020 for run in repo.checks.runs(
1021 event="workflow_dispatch", workflow=RELEASE_WORKFLOW, limit=RECENT_RUNS
1022 )
1023 if run.workflow.rsplit("/", 1)[-1] == RELEASE_WORKFLOW
1024 )
1025
1026
1027#: Seconds between the train's polls of the wave's runs.
1028_WAVE_POLL = 5.0
1029
1030
1031def _wave_runs_answered(
1032 repo: Repository, transient: Transient, *, interval: float = _WAVE_POLL
1033) -> tuple[Run, ...]:
1034 """The wave's runs, asked again while the forge does not answer.
1035
1036 An unreadable poll is a retry, as ``fm ci.status --wait`` treats it:
1037 *transient* counts the run of them, and a spent budget ends the train
1038 with the forge's words and the command that follows the wave, which
1039 runs on in CI whatever happens here.
1040 """
1041 try:
1042 return follow(
1043 repo,
1044 lambda: _wave_runs(repo),
1045 subject=_WAVE_SUBJECT,
1046 interval=interval,
1047 timeout=None,
1048 quiet=None,
1049 transient=transient,
1050 )
1051 except ForgeUnreachable as exc:
1052 fail(exc.line.strip())
1053
1054
1055def _wave_subject() -> str:
1056 """What a spent budget names: the wave runs on, and the verb that follows it."""
1057 return (
1058 "the wave runs on in CI; follow it with"
1059 f" `{footman.prog()} ci.status --point=release --wait`"
1060 )
1061
1062
1063_WAVE_SUBJECT = _wave_subject
1064
1065
1066def await_wave(
1067 repo: Repository,
1068 *,
1069 before: set[int],
1070 timeout: float = 1800.0,
1071 interval: float = _WAVE_POLL,
1072 transient: Transient | None = None,
1073) -> int | None:
1074 """The id of the newest wave run not in *before*, or ``None`` when none appears.
1075
1076 Any state counts: a wave that already finished by the time the
1077 poll saw it is still the wave that ran, and a confirmation that
1078 demanded a live run would miss a fast forge. An unreadable poll is
1079 retried within *transient*'s budget.
1080 """
1081
1082 def new_run() -> int | Pending:
1083 new = [run for run in _wave_runs(repo) if run.id not in before]
1084 return new[0].id if new else Pending()
1085
1086 try:
1087 return follow(
1088 repo,
1089 new_run,
1090 subject=_WAVE_SUBJECT,
1091 interval=interval,
1092 timeout=timeout,
1093 quiet=None,
1094 transient=transient,
1095 )
1096 except ForgeUnreachable as exc:
1097 fail(exc.line.strip())
1098 except FollowTimedOut:
1099 return None
1100
1101
1102def dispatch_flow(
1103 root: Path,
1104 repo: Repository,
1105 *,
1106 base: str = "main",
1107 at: str = "",
1108 workshop: str = "",
1109 again: bool = False,
1110 timeout: float = 60.0,
1111 interval: float = 2.0,
1112) -> list[str]:
1113 """Dispatch the wave for a merged, unpublished release, or say why not.
1114
1115 Reads the manifest on ``origin/<base>`` after a fetch, whatever
1116 commit this checkout stands on, or at *at*, an older release squash
1117 a later release has moved past. A checkout behind the base would
1118 otherwise send the wave to the squash a later release took over.
1119 *workshop* names a released driver for the wave instead of the
1120 squash's own, the recovery for a wave whose workshop was the fault;
1121 empty runs the squash's. Green when there is none, or when
1122 every member's receipt tag is already on the remote: the
1123 manifest is permanent residue of the last release, so presence
1124 is not the signal, missing receipts are. A wave already in
1125 flight is reported green with its run id. A wave that already ran
1126 at the squash with the squash's own driver and ended failure is
1127 reported green too, with its run and the recoveries, and nothing
1128 is dispatched: the same wave fails the same way, and every merge
1129 would otherwise start one more copy of it. *again* dispatches it
1130 anyway, the gesture by hand once the cause is gone, and a named
1131 *workshop* is another wave. Otherwise the wave is dispatched on
1132 *base* with the commit that stamped the manifest as its ``ref``
1133 input, never this run's own sha, so an unrelated merge landing
1134 first cannot move the wave onto another tree; the dispatch is
1135 confirmed by the run id that appears, or refused with the reason.
1136 Remote state only, receipts by ``ls-remote`` and runs by the
1137 forge, so any checkout answers the same as CI.
1138 """
1139 from livery.workshop._publish import MANIFEST, read_manifest
1140
1141 where = at or _base_ref(root, base)
1142 text = git.file_at(root, where, MANIFEST)
1143 recorded = read_manifest(text) if text else None
1144 if not recorded:
1145 return [f" no release manifest at {where}: nothing to dispatch"]
1146 cut = set(git.remote_tags(root))
1147 receipts = [f"packages/{directory}/v{version}" for directory, version in recorded]
1148 missing = [tag for tag in receipts if tag not in cut]
1149 if not missing:
1150 return [f" every receipt is cut ({', '.join(receipts)}): nothing to dispatch"]
1151 live = [run for run in _wave_runs(repo) if run.status != "completed"]
1152 if live:
1153 return [
1154 f" the wave is already in flight: run {live[0].id};"
1155 f" uncut so far: {', '.join(missing)}"
1156 ]
1157 stamping = at or git.last_commit_touching(root, MANIFEST, ref=where)
1158 if not stamping:1158 ↛ 1159line 1158 didn't jump to line 1159 because the condition on line 1158 was never true
1159 return [
1160 f" {MANIFEST} is at {where} but no commit touches it: nothing to dispatch"
1161 ]
1162 _require_release_squash(root, stamping, base)
1163 if not workshop and not again:
1164 failed = _failed_wave_at(root, repo, stamping)
1165 if failed is not None:
1166 prog = footman.prog()
1167 return [
1168 f" a wave already ran at {stamping[:12]} and ended failure: run"
1169 f" {failed.id} ({repo.web_url()}/actions/runs/{failed.id}); the same"
1170 f" wave fails the same way, so none is dispatched. Uncut:"
1171 f" {', '.join(missing)}",
1172 f" to run it again once the cause is gone: `{prog}"
1173 " workflow.release.dispatch --again`; with a released driver:"
1174 f" `--workshop=<version>`; to give the release up: `{prog}"
1175 " workflow.release --abandon`",
1176 ]
1177 seen = {run.id for run in _wave_runs(repo)}
1178 inputs = {"ref": stamping}
1179 if workshop:
1180 inputs["workshop"] = workshop
1181 try:
1182 repo.checks.dispatch(RELEASE_WORKFLOW, ref=base, inputs=inputs)
1183 except ForgeError as error:
1184 # Red, never a printed line: the merge point's verdict is the
1185 # exit code, and a wave that did not start leaves the release
1186 # uncut until someone reads the log.
1187 fail(
1188 f"the forge refused the dispatch: {error}; uncut:"
1189 f" {', '.join(missing)}. Nothing started; on GitHub the job"
1190 " needs the actions: write grant, and the recovery by hand"
1191 f" is `{footman.prog()} workflow.release.dispatch`"
1192 )
1193 import time
1194
1195 deadline = time.monotonic() + timeout
1196 while time.monotonic() < deadline:
1197 new = [run for run in _wave_runs(repo) if run.id not in seen]
1198 if new:
1199 driver = f" driven by {workshop}" if workshop else ""
1200 return [
1201 f" dispatched the wave at {stamping[:12]}{driver}: run {new[0].id};"
1202 f" uncut: {', '.join(missing)}"
1203 ]
1204 time.sleep(interval)
1205 return [
1206 " the dispatch was accepted but no wave run appeared within"
1207 f" {timeout:.0f}s; re-run `{footman.prog()} workflow.release.dispatch`,"
1208 " which reports a wave that has since appeared"
1209 ]
1210
1211
1212def _failed_wave_at(root: Path, repo: Repository, squash: str) -> Run | None:
1213 """The newest dispatched wave about *squash* that ended failure, or None.
1214
1215 The runs about the squash are the forge's listing for it and the
1216 runs that recorded themselves as its (`runs_about`), since a wave
1217 the forge filed under a tip that moved on is still the squash's.
1218 A cancelled wave, or one that never ran, is not a failure here:
1219 the next merge dispatches again for those, as for a died merge
1220 run.
1221 """
1222 from livery.workshop._traces import runs_about
1223
1224 caused, _lines = runs_about(root, repo, squash)
1225 ids = {item.run_id for item in caused if item.event == "workflow_dispatch"}
1226 failed = [
1227 run
1228 for run in _wave_runs(repo)
1229 if str(run.id) in ids
1230 and run.status == "completed"
1231 and run.conclusion == "failure"
1232 ]
1233 return max(failed, key=lambda run: run.id) if failed else None
1234
1235
1236def _require_release_squash(root: Path, stamping: str, base: str) -> None:
1237 """Refuse to send the wave to a commit the wave itself would refuse.
1238
1239 The wave publishes only from a release squash, recognised by the
1240 ``Mined-At`` line the pull request body becomes at the merge. The
1241 last commit touching the manifest on a release branch is the
1242 branch's own stamp commit, which carries no such line, so a
1243 dispatch from a checkout left on that branch would send a wave
1244 that refuses. The refusal names the squash on the base instead.
1245 """
1246 from livery.workshop._publish import mined_at
1247
1248 if mined_at(git.commit_message(root, stamping)):
1249 return
1250 squash, subject = newest_release_squash(root, base)
1251 prog = footman.prog()
1252 if squash:1252 ↛ 1253line 1252 didn't jump to line 1253 because the condition on line 1252 was never true
1253 where = (
1254 f"the newest release squash on origin/{base} is {squash[:12]}"
1255 f" ({subject}); run `{prog} workflow.release.dispatch` from {base},"
1256 f" or `{prog} workflow.release.dispatch --at={squash[:12]}` here"
1257 )
1258 else:
1259 where = f"origin/{base} holds no release squash in its recent history"
1260 fail(
1261 f"{stamping[:12]} carries no Mined-At line: it is a branch's stamp"
1262 " commit, not a release squash, and the wave would refuse it."
1263 f" {where}"
1264 )
1265
1266
1267def newest_release_squash(root: Path, base: str = "main") -> tuple[str, str]:
1268 """The newest release squash on the base, as (sha, subject); ("", "") when none."""
1269 from livery.workshop._publish import mined_at
1270
1271 for sha, subject in git.recent_commits(root, 50, ref=_base_ref(root, base)):
1272 if subject.startswith("chore(release): released") and mined_at(1272 ↛ 1275line 1272 didn't jump to line 1275 because the condition on line 1272 was never true
1273 git.commit_message(root, sha)
1274 ):
1275 return sha, subject
1276 return "", ""
1277
1278
1279def _base_ref(root: Path, base: str) -> str:
1280 """``origin/<base>`` after a fetch when the clone knows it, else HEAD.
1281
1282 The release squashes live on the base. HEAD equals the base on the
1283 merge point and on a person's main, and differs on a release
1284 branch, whose history lacks the squash it was merged as; a clone
1285 without the remote (a rig) has only HEAD.
1286 """
1287 with contextlib.suppress(git.GitError):
1288 git.fetch(root)
1289 try:
1290 git.object_id(root, f"origin/{base}")
1291 except git.GitError:
1292 return "HEAD"
1293 return f"origin/{base}"
1294
1295
1296def pending_release_waves(
1297 root: Path, base: str = "main"
1298) -> tuple[tuple[str, tuple[str, ...]], ...]:
1299 """Every recent release squash whose receipts are not all cut, oldest first.
1300
1301 A merged release whose wave died leaves the squash on the base
1302 with the stamps and changelogs landed and receipt tags missing.
1303 Re-preparing from that state derives an empty release (measured:
1304 an empty pull request the forge never agrees to merge), so the
1305 recovery is the wave at the squash, never a new pull request.
1306 Every release squash in the base's recent history is consulted, so
1307 a later release never strands an earlier died wave, and a checkout
1308 standing on a release branch still finds the squash it was merged
1309 as. A later release squash naming a package takes over that
1310 package's uncut receipt, so a squash abandoned for a new release
1311 (`fm workflow.release --abandon`) is never offered again. Each
1312 entry is the squash sha and its missing receipt tags.
1313 """
1314 from livery.workshop._publish import discover_release
1315
1316 cut = set(git.remote_tags(root))
1317 pending: list[tuple[str, tuple[str, ...]]] = []
1318 # Newest first: the packages a later release squash names.
1319 taken: set[str] = set()
1320 for sha, subject in git.recent_commits(root, 50, ref=_base_ref(root, base)):
1321 if not subject.startswith("chore(release): released"):
1322 continue
1323 released = discover_release(root, sha)
1324 missing = tuple(
1325 f"{package.path}/v{version}"
1326 for package, version in released
1327 if f"{package.path}/v{version}" not in cut and package.path not in taken
1328 )
1329 taken.update(package.path for package, _version in released)
1330 if missing:
1331 pending.append((sha, missing))
1332 pending.reverse()
1333 return tuple(pending)
1334
1335
1336def pending_release_wave(root: Path) -> tuple[str, tuple[str, ...]] | None:
1337 """The oldest release squash with an uncut receipt, or None.
1338
1339 The set-blind selection, for a dispatch with no set named:
1340 recoveries run in order, oldest first.
1341 """
1342 waves = pending_release_waves(root)
1343 return waves[0] if waves else None
1344
1345
1346def pending_release_wave_for(
1347 root: Path, members: tuple[Package, ...]
1348) -> tuple[str, tuple[str, ...]] | None:
1349 """The oldest uncut squash whose receipts touch *members*, or None.
1350
1351 A release of one set must find its own died wave even when an
1352 older squash of another set is uncut too: that squash is the
1353 other set's recovery, named by the caller, never a reason to
1354 prepare this set again from a tree already stamped.
1355 """
1356 for sha, missing in pending_release_waves(root):
1357 if uncut_in_set(missing, members):
1358 return (sha, missing)
1359 return None
1360
1361
1362def uncut_in_set(
1363 missing: tuple[str, ...], members: tuple[Package, ...]
1364) -> tuple[str, ...]:
1365 """The uncut receipts, `packages/<member>/v<x>`, that belong to *members*."""
1366 names = {member.member for member in members}
1367 return tuple(tag for tag in missing if receipt_member(tag) in names)
1368
1369
1370release_group = workflow.group("release", help="The release train")
1371
1372
1373@release_group.default(interactive=True)
1374def workflow_release(
1375 *paths: str,
1376 armed: Annotated[bool, doc("arm the release PR to merge on green")] = False,
1377 local: Annotated[
1378 bool, doc("derive, build, validate, report; nothing leaves the machine")
1379 ] = False,
1380 force_unverified_base: Annotated[
1381 bool, doc("release without waiting for the base's own CI")
1382 ] = False,
1383 workshop: Annotated[
1384 str, doc("a released livery-workshop version to drive a re-dispatched wave")
1385 ] = "",
1386 abandon: Annotated[
1387 bool,
1388 doc(
1389 "prepare a new release over a died wave of this set instead of"
1390 " re-dispatching it"
1391 ),
1392 ] = False,
1393) -> None:
1394 """Release a set of packages: the branch decides the act.
1395
1396 Names the set positionally (``packages/forge`` or just ``forge``).
1397 On a main-family branch this is the release train: one PR,
1398 receipts per member, re-running the recovery at every step;
1399 ``--armed`` follows the pull request to its squash and the wave
1400 to its verdict, from main, the way ``submit --armed`` follows a
1401 feature pull request, and an unarmed run returns at once. On
1402 any other branch it is the dev act: a wheel straight from the
1403 branch at a dev version, published only to the configured custom
1404 index after a confirmation, no reserved branch, no PR, no tags.
1405 ``--local`` is everything that stays on this machine, on either
1406 branch mode. ``--workshop`` applies only to the recovery of a
1407 died wave: the named release drives the wave in place of the
1408 squash's own workshop. ``--abandon`` gives up that recovery: when
1409 no released workshop can drive the died wave, a new release of
1410 the set takes its uncut receipts over.
1411 """
1412 from livery.workshop._dev_release import dev_release
1413 from livery.workshop._extensions import workspace_root
1414 from livery.workshop._forge_lane import this_repository
1415
1416 root = workspace_root()
1417 if root is None:1417 ↛ 1418line 1417 didn't jump to line 1418 because the condition on line 1417 was never true
1418 fail("no workspace: no workshop.toml above the working directory")
1419 if not paths:1419 ↛ 1420line 1419 didn't jump to line 1420 because the condition on line 1419 was never true
1420 fail(
1421 f"name the set: `{footman.prog()} workflow.release forge` (one package) or"
1422 f" `{footman.prog()} workflow.release forge workshop` (an atomic set)"
1423 )
1424 members = resolve_set(root, tuple(paths))
1425 branch = git.current_branch(root)
1426 if not branch:
1427 fail(
1428 "HEAD is detached, and the branch decides the act. Check out a"
1429 " branch (main for the release train, any feature branch for a"
1430 " dev build), then run this again."
1431 )
1432 if not runs_the_train(branch):
1433 dev_release(root, members, local=local)
1434 return
1435 if local:
1436 local_release(root, members)
1437 return
1438 print(f" act: release train, from '{branch}'")
1439 pending = pending_release_wave_for(root, members)
1440 repo = this_repository(root)
1441 if abandon:1441 ↛ 1454line 1441 didn't jump to line 1454 because the condition on line 1441 was always true
1442 if pending is None:
1443 fail(
1444 "--abandon gives up a died wave of this set, and no release"
1445 " squash has an uncut receipt in it; drop the flag to prepare"
1446 " a release"
1447 )
1448 squash, missing = pending
1449 print(
1450 f" release squash {squash[:12]} abandoned; this release takes over"
1451 f" its uncut receipts: {', '.join(uncut_in_set(missing, members))}"
1452 )
1453 pending = None
1454 if pending is not None:1454 ↛ 1455line 1454 didn't jump to line 1455 because the condition on line 1454 was never true
1455 squash, missing = pending
1456 print(f" release squash {squash[:12]} has uncut receipts:")
1457 for name in missing:
1458 print(f" {name}")
1459 # CI publishes, never this machine: the wave is dispatched
1460 # at the squash, the duplicate-tolerant wave walks past what
1461 # an earlier attempt already did, and nothing new prepares.
1462 print(" dispatching the wave at the squash; nothing new prepares")
1463 for line in dispatch_flow(root, repo, at=squash, workshop=workshop):
1464 print(line)
1465 print(" re-run to release work newer than the squash")
1466 return
1467 for squash, missing in pending_release_waves(root):
1468 # An uncut receipt outside this set is that set's recovery,
1469 # named so a person can run it; this release goes ahead.
1470 inside = uncut_in_set(missing, members)
1471 missing = tuple(tag for tag in missing if tag not in inside)
1472 if not missing:1472 ↛ 1474line 1472 didn't jump to line 1474 because the condition on line 1472 was always true
1473 continue
1474 others = " ".join(sorted({receipt_member(tag) for tag in missing}))
1475 print(
1476 f" release squash {squash[:12]} has uncut receipts outside this"
1477 f" set: {', '.join(missing)}; `{footman.prog()} workflow.release"
1478 f" {others}` re-dispatches its wave"
1479 )
1480 if workshop:1480 ↛ 1481line 1480 didn't jump to line 1481 because the condition on line 1480 was never true
1481 fail(
1482 "--workshop pins the driver of a re-dispatched wave, and no"
1483 " release squash has an uncut receipt; drop the flag to prepare"
1484 " a release"
1485 )
1486 run_release(
1487 partial(
1488 ReleaseDriver,
1489 root,
1490 repo,
1491 members,
1492 armed=armed,
1493 force_unverified_base=force_unverified_base,
1494 ),
1495 repo,
1496 root,
1497 armed=armed,
1498 )
1499
1500
1501def run_release(
1502 make_driver: Callable[[], ReleaseDriver],
1503 repo: Repository,
1504 root: Path,
1505 *,
1506 armed: bool,
1507) -> None:
1508 """Drive a release through the engine; an armed one re-derives a stale set.
1509
1510 An armed release whose follow ends red because the base moved
1511 under its set prepares again on the moved base and follows again,
1512 up to [livery.workshop._release_driver.REDERIVE_LIMIT] prepares
1513 in all; any other red is the release's verdict and exits with it.
1514 """
1515 for attempt in range(1, REDERIVE_LIMIT + 1):1515 ↛ exitline 1515 didn't return from function 'run_release' because the loop on line 1515 didn't complete
1516 driver = make_driver()
1517 try:
1518 run_workflow(driver, repo, root)
1519 return
1520 except SystemExit:
1521 if (
1522 not armed
1523 or attempt == REDERIVE_LIMIT
1524 or not set_moved(repo, root, driver.name)
1525 ):
1526 raise
1527 print(
1528 f" {driver.branch}: the base moved under the set while its pull"
1529 f" request waited; re-deriving ({attempt} of"
1530 f" {REDERIVE_LIMIT - 1} re-derives)"
1531 )
1532
1533
1534#: How many times an armed release prepares in all: the first prepare
1535#: and its re-derives on a base that keeps moving under the set. A
1536#: base that moves faster than a release can prepare is a repository
1537#: where releases need merges held, and saying so beats looping.
1538REDERIVE_LIMIT = 3
1539
1540
1541def set_moved(repo: Repository, root: Path, name: str) -> bool:
1542 """Whether release *name*'s open pull request is stale in its set's paths."""
1543 from livery.workshop._workflow_state import workflow_states
1544
1545 git.fetch(root)
1546 return any(
1547 wf.name == name and wf.blocker.name == "STALE_SET"
1548 for wf in workflow_states(repo, root)
1549 )
1550
1551
1552@release_group.task(name="dispatch")
1553def workflow_release_dispatch(
1554 at: Annotated[
1555 str, doc("an older release squash to dispatch instead of HEAD's")
1556 ] = "",
1557 workshop: Annotated[
1558 str, doc("a released livery-workshop version to drive the wave")
1559 ] = "",
1560 again: Annotated[
1561 bool, doc("dispatch although a wave already failed at the squash")
1562 ] = False,
1563) -> None:
1564 """Dispatch the release wave for a merged, unpublished release; green otherwise.
1565
1566 The merge point's last task, and the recovery gesture by hand:
1567 it reads the manifest at HEAD and the receipts on the remote, so
1568 on a normal day it prints green, after a died merge run it
1569 dispatches, a wave in flight is reported with its run id, and a
1570 wave that already failed at the squash is reported with its run
1571 and dispatched again only on ``--again``. ``--at`` names an older
1572 release squash a later release has moved past; ``--workshop``
1573 names a released driver for a wave whose own workshop was the
1574 fault.
1575 """
1576 from livery.workshop._extensions import workspace_root
1577 from livery.workshop._forge_lane import this_repository
1578
1579 root = workspace_root()
1580 if root is None:
1581 fail("no workspace: no workshop.toml above the working directory")
1582 for line in dispatch_flow(
1583 root, this_repository(root), at=at, workshop=workshop, again=again
1584 ):
1585 print(line)
1586
1587
1588@release_group.task(name="check-title", hidden=True)
1589def workflow_release_check_title(
1590 title: Annotated[str, doc("the PR title CI observed")] = "",
1591) -> None:
1592 """Verify a release PR's title against the release's member list.
1593
1594 The publish wave discovers a release from the squash's member
1595 list; the title is presentation. This job keeps the two
1596 consistent: the gate job runs this first, so a title that no
1597 longer names what the list prepared is refused before the
1598 union and the verdict, and the merge waits for a person to fix
1599 the title. Without ``--title`` the title
1600 comes from the runner's event payload; a run that is not a pull
1601 request, or a pull request off a release branch, is green here
1602 and says so.
1603 """
1604 from livery.workshop._extensions import workspace_root
1605
1606 root = workspace_root()
1607 if root is None:1607 ↛ 1608line 1607 didn't jump to line 1608 because the condition on line 1607 was never true
1608 fail("no workspace: no workshop.toml above the working directory")
1609 if not title:
1610 # The shell passes no title: the event payload names it, and
1611 # names the head branch too. An explicit --title is always
1612 # checked, whatever branch the runner is on.
1613 from livery.workshop._ci_context import event_payload
1614
1615 pull = (event_payload() or {}).get("pull_request") or {}
1616 title = str(pull.get("title") or "")
1617 if not title:
1618 print(" not a pull request: no title to check")
1619 return
1620 head_ref = str((pull.get("head") or {}).get("ref") or "")
1621 if head_ref and not head_ref.startswith("workflow/release/"):1621 ↛ 1624line 1621 didn't jump to line 1624 because the condition on line 1621 was always true
1622 print(f" {head_ref} is not a release branch: nothing to check")
1623 return
1624 branch = git.current_branch(root)
1625 recorded = member_pairs_at(root, "HEAD")
1626 if not recorded:1626 ↛ 1627line 1626 didn't jump to line 1627 because the condition on line 1626 was never true
1627 print(f" {branch}: no release member list; nothing to check")
1628 return
1629 expected = release_title(recorded)
1630 if title and title != expected:
1631 fail(
1632 f"the PR title does not match what the member list prepared:\n"
1633 f" title: {title}\n prepared: {expected}\n"
1634 " The title is presentation rebuilt from the branch's"
1635 " member list; restore it or re-run workflow.release."
1636 )
1637 print(f" title matches the prepared release: {expected}")
1638
1639
1640@release_group.task(name="check-fresh", hidden=True)
1641def workflow_release_check_fresh(
1642 head: Annotated[str, doc("the pull request's head branch")] = "",
1643 base: Annotated[str, doc("the branch it merges into")] = "",
1644) -> None:
1645 """Refuse a release pull request whose base moved in its set's paths.
1646
1647 The gate job runs this last, so the time between the check and
1648 the merge it allows is as short as the forge makes it. The
1649 release's manifest names its members and the commit the prepare
1650 mined at; a commit the base gained since then under a member's
1651 directory is code the stamped changelog does not cover, and the
1652 squash's publish would refuse it after the merge, where nothing
1653 can fix the squash. Refused here, the pull request waits while
1654 `workflow.release` re-derives it in place. Without ``--head`` the
1655 branches come from the runner's event payload; a run that is not
1656 a pull request, or one off a release branch, is green and says so.
1657 """
1658 import json
1659
1660 from livery.workshop._extensions import workspace_root
1661 from livery.workshop._publish import MANIFEST, read_manifest
1662
1663 root = workspace_root()
1664 if root is None:1664 ↛ 1665line 1664 didn't jump to line 1665 because the condition on line 1664 was never true
1665 fail("no workspace: no workshop.toml above the working directory")
1666 if not head:1666 ↛ 1667line 1666 didn't jump to line 1667 because the condition on line 1666 was never true
1667 from livery.workshop._ci_context import event_payload
1668
1669 pull = (event_payload() or {}).get("pull_request") or {}
1670 if not pull:
1671 print(" not a pull request: nothing to check")
1672 return
1673 head = str((pull.get("head") or {}).get("ref") or "")
1674 base = base or str((pull.get("base") or {}).get("ref") or "")
1675 if not head.startswith("workflow/release/"):
1676 print(f" {head or 'this branch'} is not a release branch: nothing to check")
1677 return
1678 base = base or "main"
1679 text = git.file_at(root, "HEAD", MANIFEST)
1680 pairs = read_manifest(text) if text else None
1681 mined = ""
1682 if pairs:1682 ↛ 1685line 1682 didn't jump to line 1685 because the condition on line 1682 was always true
1683 with contextlib.suppress(ValueError, TypeError, AttributeError):
1684 mined = str(json.loads(text).get("mined-at") or "")
1685 if not pairs or not mined:
1686 print(f" {MANIFEST} records no mining point: nothing to check")
1687 return
1688 git.fetch(root)
1689 paths = tuple(f"packages/{directory}" for directory, _ in pairs)
1690 moved = git.log_paths(root, f"{mined}..origin/{base}", paths)
1691 if moved:
1692 listed = "\n".join(f" {subject}" for subject in moved)
1693 members = " ".join(directory for directory, _ in pairs)
1694 fail(
1695 f"{base} moved under this release since its prepare at"
1696 f" {mined[:12]}:\n{listed}\n Merged, the squash would ship code"
1697 " its changelog does not cover. `"
1698 f"{footman.prog()} workflow.release {members}` re-derives it in"
1699 " place; an armed release does that itself."
1700 )
1701 print(f" fresh: {base} has not moved under {', '.join(paths)} since {mined[:12]}")
1702
1703
1704@release_group.task(name="publish", hidden=True)
1705def workflow_release_publish(
1706 ref: Annotated[str, doc("the release squash; empty means HEAD")] = "",
1707 prebuilt: Annotated[
1708 bool, doc("trust the dist/ the run collected for each member a job builds")
1709 ] = False,
1710) -> None:
1711 """Publish the squash at --ref: the wave, receipts cut per member.
1712
1713 The CI entry point after a release PR merges, and the recovery
1714 entry when a publish died mid-wave: everything already tagged is
1715 walked past. ``--ref`` exists because HEAD usually moves past the
1716 squash before a recovery runs. Each member publishes to the
1717 registry of the ecosystem its extensions release it to, and the
1718 wave reads what that registry serves through the probe they answer:
1719 the resolved index for a python package, the resolved conan target
1720 for a conan recipe that names a reference.
1721 ``--prebuilt`` says the jobs of the run already built the members
1722 they build before the wave, the workspace's ``job-built-members``
1723 answer: a platform-wheel member's dist/ holds the wheels collected
1724 from every platform, a conan member's the caches saved on every
1725 host, and the wave publishes them instead of building on this
1726 runner alone. Inside CI the wave decides that for itself: such a
1727 member whose dist/ already holds a file was fed by the run, since
1728 a runner's checkout starts with none.
1729 """
1730 import os
1731
1732 from livery.workshop._extensions import workspace_root
1733 from livery.workshop._publish import Registry, publish_release
1734 from livery.workshop._registries import resolve_registry
1735
1736 root = workspace_root()
1737 if root is None:1737 ↛ 1738line 1737 didn't jump to line 1738 because the condition on line 1737 was never true
1738 fail("no workspace: no workshop.toml above the working directory")
1739 target = resolve_registry(root, "python")
1740 if not target.publish_url:1740 ↛ 1741line 1740 didn't jump to line 1741 because the condition on line 1740 was never true
1741 from livery.workshop._dev_release import INDEX_VAR
1742
1743 fail(
1744 "no publish address resolved for python: the declaration"
1745 " names only a read index, and an upload endpoint is"
1746 " never defaulted. Declare [registries.python] publish in"
1747 f" workshop.toml, or set {INDEX_VAR}."
1748 )
1749 if not prebuilt:1749 ↛ 1750line 1749 didn't jump to line 1750 because the condition on line 1749 was never true
1750 prebuilt = collected_wheels(root, ref)
1751 # Each member's probe is its extensions' answer, asked once and
1752 # polled through the wave's whole wait.
1753 probes: dict[str, Registry] = {}
1754
1755 def registry_for(package: Package) -> Registry:
1756 probe = probes.get(package.path)
1757 if probe is None:
1758 probe = probes[package.path] = _lifecycle.registry(package)
1759 return probe
1760
1761 receipts = publish_release(
1762 root,
1763 registry_for,
1764 ref=ref,
1765 index_url=target.publish_url,
1766 # UV_PUBLISH_TOKEN is the explicit override; the resolved
1767 # target's credential is the same seam the probe reads, so a
1768 # forge registry publishes with the lane token unprompted.
1769 token=os.environ.get("UV_PUBLISH_TOKEN", "") or target.token,
1770 prebuilt=prebuilt,
1771 )
1772 print(f" wave: {len(receipts)} member(s) published")
1773
1774
1775def collected_wheels(root: Path, ref: str) -> bool:
1776 """Whether the run collected what a job built for this wave, judged inside CI alone.
1777
1778 The members a job builds before the wave are the workspace's
1779 ``job-built-members`` answer. A runner's checkout starts with no
1780 dist/, so a file in such a member's dist/ was collected from that
1781 job's artifact, and the wave trusts the collection; each member it
1782 trusts is printed with its job. Outside CI a dist/ may hold a stale
1783 local build, and the wave builds as asked.
1784 """
1785 from livery.workshop._ci_context import run_context
1786 from livery.workshop._publish import collected, discover_release
1787 from livery.workshop._queries import JOB_BUILT_MEMBERS, answer
1788
1789 if run_context() is None:
1790 return False
1791 built = answer(root, JOB_BUILT_MEMBERS)
1792 fed = False
1793 for package, _version in discover_release(root, ref or git.head_sha(root)):
1794 job = built.get(package.path)
1795 if job is not None and collected(package):
1796 print(
1797 f" prebuilt: {package.name}: the run collected what the {job} job"
1798 " built"
1799 )
1800 fed = True
1801 return fed