From c7b9160f1869dab3fdc8fc58b6a191d02215d6a0 Mon Sep 17 00:00:00 2001 From: Danathar Date: Mon, 21 Sep 2026 01:17:31 +0000 Subject: [PATCH 1/2] docs: close README/skill package-count drift against the manifests README.md and docs/skills/package-contract.md hand-quoted 61/12/4 for the Bluefin/Utah-additions/unavailable package counts while packages/utah.toml's [unavailable] list had grown to 9 tracked gaps and [parity] to 28 entries -- the docs said 4, the manifest said 9. Recompute both from generate-site-data.py's own build() (58/44/9, matching site/data/packages.json) and add scripts/check-doc-counts.py, wired into 'just check', so the two cannot silently diverge again. Also: - Drop the stale 'pipewire-libs-extra is missing' gap: packages/utah.toml's own header records it as returned to the install contract, and it is one of the 58 packages the manifests now show installed. - Stop the README's top banner and 'Nothing is published' bullet from claiming the installer/offline payload is unimplemented -- the live ISO's bootc-installer already passes an offline, LUKS2-encrypted install in local QEMU validation (docs/verification/README.md). State publication status separately from that local implementation status. - Point docs/building.md's quickstart at the ISO/E2E/rollback-adjacent gates that already exist (just iso, boot-iso, luks-test, try-installed, check-desktop-contract, check-repos) instead of leaving them undiscovered in skills/local-testing.md. Part of #24 (Utah/Dakota release-readiness gaps), specifically #23's documentation-accuracy acceptance criteria. Assisted-by: Claude Sonnet 5 via omp/hive Signed-off-by: Danathar --- Justfile | 3 ++ README.md | 36 ++++++++----- docs/building.md | 23 +++++++++ docs/skills/package-contract.md | 9 ++-- scripts/check-doc-counts.py | 91 +++++++++++++++++++++++++++++++++ tests/test_check_doc_counts.py | 69 +++++++++++++++++++++++++ 6 files changed, 214 insertions(+), 17 deletions(-) create mode 100755 scripts/check-doc-counts.py create mode 100644 tests/test_check_doc_counts.py diff --git a/Justfile b/Justfile index 95ba1a907..b5f4d5e80 100644 --- a/Justfile +++ b/Justfile @@ -93,6 +93,9 @@ check: # The status page's package grid is generated from the manifests; a stale # committed copy would publish a list the image no longer installs. python3 scripts/generate-site-data.py --check + # README.md and docs/skills/package-contract.md quote the same package + # counts by hand; catch it before the manifests move and the prose does not. + python3 scripts/check-doc-counts.py python3 scripts/install-packages.py --check --repos-dir packages packages/bluefin.toml python3 scripts/verify-rpm-contract.py --check packages/bluefin.toml # run the host-side unit suite (tests/test_*.py) via its dedicated recipe diff --git a/README.md b/README.md index 458c5c27d..0515681c5 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,15 @@ Bluefin built on Fedora Hummingbird. The more ... civilized murder machine. ![alt](https://github.com/user-attachments/assets/56428338-54a0-4376-a53b-5f02f8b101a1) -**Experimental pre-alpha** — the image builds, boots, and reaches GDM in local -QEMU validation. No image has been published to a registry, there is no -installer payload, and no ISO has been released. Nothing here is ready to run on -a machine you care about. [Filing +**Experimental pre-alpha** — the image builds, boots, and installs end to +end in local QEMU validation: the live ISO's bootc-installer creates a +LUKS2-encrypted disk from the ISO's embedded container store with no +network, and the installed system boots on its own to GDM and a GNOME +session (verified record: [docs/verification](docs/verification/README.md)). +None of that is published — no image has been pushed to a registry and no +ISO has been released — but the installer and offline payload it exercises +are implemented, not a future milestone. Nothing here is ready to run on a +machine you care about. [Filing issues](https://github.com/projectbluefin/utah/issues) is the whole point. ## What it is @@ -60,12 +65,15 @@ being noticed later. | | count | | --- | --- | -| Bluefin contract installed | **61** | -| Utah additions (GNOME 51, desktop services) | 12 | -| Genuinely unavailable | **4** | +| Bluefin contract installed | **58** | +| Utah additions (GNOME 51, base-image parity, desktop services) | 44 | +| Genuinely unavailable | **9** | The install writes its resolved list to `/usr/share/utah/contract.txt` and the -verify step asserts *that file*, so the two cannot disagree. +verify step asserts *that file*, so the two cannot disagree. These counts are +generated from `packages/bluefin.toml` and `packages/utah.toml` +(`scripts/generate-site-data.py`, `site/data/packages.json`); `just check` +fails if this table drifts from that output (`scripts/check-doc-counts.py`). @@ -73,9 +81,12 @@ verify step asserts *that file*, so the two cannot disagree. This is the honest list, and it is why the label above says pre-alpha. -- **Nothing is published.** No image, no ISO artifact, no installer. A live - ISO builds locally (`just iso`); installer payload integration is the next - ISO milestone. +- **Nothing is published.** No image has been pushed to a registry and no ISO + artifact has been released. The live ISO and its bootc-installer payload + are implemented and pass an offline, LUKS2-encrypted install end to end in + local QEMU validation (`just iso`, `just luks-test`; record and screenshots + in [docs/verification](docs/verification/README.md)) — what is missing is + publication, not the installer. - **Live media boot paths and Secure Boot.** Live media requires UEFI boot; legacy BIOS and file-backed/Ventoy booting are explicitly unsupported (flash directly using Fedora Media Writer or `dd`). As a documented exception @@ -102,9 +113,6 @@ This is the honest list, and it is why the label above says pre-alpha. compiles for the base kernel. The module against the OGC kernel, the driver installer flags, and the flavored builds pulling the kernel cache image have not yet all passed in one run. -- **`pipewire-libs-extra` is missing.** It was never a Fedora package; it exists - only in negativo17's `fedora-multimedia`, which Bluefin enables for its whole - install. - **Codec support differs.** Twelve `[multimedia_overrides]` names are packages Fedora already ships and Bluefin *replaces* with negativo17 builds. Utah installs Fedora's. Nothing is absent from the image; hardware-accelerated diff --git a/docs/building.md b/docs/building.md index 56ef36b00..df94aff57 100644 --- a/docs/building.md +++ b/docs/building.md @@ -25,6 +25,29 @@ noVNC and SSH ports; SSH is available only when the image was built with unified-storage's registry repull; published images omit that argument and keep the service enabled. +## Validate the release-readiness gates + +Once `boot-vm` confirms the desktop boots, the rest of the adopted gates run +locally too: + +```bash +just iso testing 1 # build a debug live ISO (needed for luks-test) +just boot-iso # boot the live session and confirm the installer is there +just luks-test # install to an encrypted disk over SSH, boot it, log in +just try-installed # re-boot the disk luks-test installed, with a browser console +just check-desktop-contract # branding, services, and Flatpak policy against a built image +just check-repos # every contract package resolves in the enabled repositories +``` + +`just luks-test` drives `iso/scripts/luks-e2e.sh`: it installs from the ISO's +embedded container store with no network, unlocks the LUKS2 volume at the +Plymouth prompt, confirms the disk boots on its own, and overwrites +[`docs/verification/README.md`](verification/README.md) and its screenshots +with the fresh passing record (`scripts/update-e2e-readme.py`) — that file +documents exactly what a run proved and when. See +[`skills/local-testing.md`](skills/local-testing.md) for the encrypted and +plain offline install paths and the `bootc rollback` / `uupd` update policy. + ## Deep documentation | Topic | Skill | diff --git a/docs/skills/package-contract.md b/docs/skills/package-contract.md index 02bd8957a..546e208f5 100644 --- a/docs/skills/package-contract.md +++ b/docs/skills/package-contract.md @@ -134,9 +134,11 @@ about installation. - Drift in `packages/bluefin.toml` from upstream is a CI failure (`just check-parity`). -Current counts, per the README "Package parity" section: 61 Bluefin contract -packages installed, 12 Utah additions (GNOME 51, desktop services), 4 -genuinely unavailable. +Current counts, per the README "Package parity" section: 58 Bluefin contract +packages installed, 44 Utah additions (GNOME 51, base-image parity, desktop +services), 9 genuinely unavailable. `scripts/check-doc-counts.py` (part of +`just check`) recomputes these from the manifests and fails if either +document drifts from `site/data/packages.json`. ## Verification @@ -145,4 +147,5 @@ just check-parity just check-repos python3 scripts/install-packages.py --check packages/bluefin.toml python3 scripts/verify-rpm-contract.py --check packages/bluefin.toml +python3 scripts/check-doc-counts.py ``` diff --git a/scripts/check-doc-counts.py b/scripts/check-doc-counts.py new file mode 100755 index 000000000..89d1c6c40 --- /dev/null +++ b/scripts/check-doc-counts.py @@ -0,0 +1,91 @@ +#!/usr/bin/env python3 +"""Fail when the hand-written package counts drift from the manifests. + +README.md's "Package parity with Bluefin" table and docs/skills/ +package-contract.md's "Current counts" sentence quote the same three numbers +by hand: how many Bluefin contract packages Utah installs as-is, how many it +adds or supplies itself, and how many are genuinely unavailable. Those +numbers already drifted once -- packages/utah.toml's [unavailable] list grew +from 4 to 9 entries while both documents kept quoting 4 -- so this recomputes +them from generate-site-data.py's own build() (the same function that writes +site/data/packages.json) and fails loudly instead of letting prose lie about +the manifests again. +""" + +from __future__ import annotations + +import importlib.util +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +README = ROOT / "README.md" +PACKAGE_CONTRACT_SKILL = ROOT / "docs/skills/package-contract.md" + + +def load_generator(): + spec = importlib.util.spec_from_file_location( + "generate_site_data", ROOT / "scripts" / "generate-site-data.py") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def expected_counts() -> tuple[int, int, int]: + """(Bluefin contract installed, Utah additions, genuinely unavailable).""" + data = load_generator().build(ROOT) + bluefin = next(g for g in data["groups"] if g["id"] == "bluefin") + bluefin_count = len(bluefin["packages"]) + installed = data["totals"]["installed"] + unavailable = data["totals"]["unavailable"] + return bluefin_count, installed - bluefin_count, unavailable + + +def find(pattern: str, text: str, path: Path) -> int: + match = re.search(pattern, text) + if not match: + print(f"error: {path} is missing the expected package-count wording " + f"(pattern not found: {pattern!r})", file=sys.stderr) + raise SystemExit(1) + return int(match.group(1)) + + +def main() -> int: + bluefin, additions, unavailable = expected_counts() + + readme = README.read_text() + readme_bluefin = find(r"Bluefin contract installed \| \*\*(\d+)\*\*", readme, README) + readme_additions = find(r"Utah additions \([^)]*\) \| (\d+)", readme, README) + readme_unavailable = find(r"Genuinely unavailable \| \*\*(\d+)\*\*", readme, README) + + skill = re.sub(r"\s+", " ", PACKAGE_CONTRACT_SKILL.read_text()) + skill_bluefin = find(r"(\d+) Bluefin contract packages installed", skill, + PACKAGE_CONTRACT_SKILL) + skill_additions = find(r"(\d+) Utah additions \([^)]*\)", skill, PACKAGE_CONTRACT_SKILL) + skill_unavailable = find(r"(\d+) genuinely unavailable", skill, PACKAGE_CONTRACT_SKILL) + found = { + "README.md Bluefin contract installed": (readme_bluefin, bluefin), + "README.md Utah additions": (readme_additions, additions), + "README.md Genuinely unavailable": (readme_unavailable, unavailable), + "package-contract.md Bluefin contract installed": (skill_bluefin, bluefin), + "package-contract.md Utah additions": (skill_additions, additions), + "package-contract.md genuinely unavailable": (skill_unavailable, unavailable), + } + + stale = {label: (actual, want) for label, (actual, want) in found.items() if actual != want} + if stale: + print("error: documented package counts are stale. Regenerate with " + "`python3 scripts/generate-site-data.py` and update the prose " + "to match:", file=sys.stderr) + for label, (actual, want) in stale.items(): + print(f" {label}: documented {actual}, manifests say {want}", file=sys.stderr) + return 1 + + print(f"documented package counts are current: {bluefin} Bluefin contract, " + f"{additions} Utah additions, {unavailable} genuinely unavailable") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_check_doc_counts.py b/tests/test_check_doc_counts.py new file mode 100644 index 000000000..1fc23c755 --- /dev/null +++ b/tests/test_check_doc_counts.py @@ -0,0 +1,69 @@ +"""The hand-written package counts in README.md and package-contract.md must +not be able to drift from the manifests the way they already did once: +packages/utah.toml's [unavailable] list grew from 4 to 9 entries while both +documents kept quoting 4. +""" + +from __future__ import annotations + +import importlib.util +import re +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SCRIPT = ROOT / "scripts" / "check-doc-counts.py" + + +def load_module(): + spec = importlib.util.spec_from_file_location("check_doc_counts", SCRIPT) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +class CheckDocCountsTests(unittest.TestCase): + def setUp(self): + self.module = load_module() + + def test_committed_docs_match_the_manifests(self): + result = subprocess.run( + [sys.executable, str(SCRIPT)], capture_output=True, text=True) + self.assertEqual(result.returncode, 0, result.stderr) + + def test_expected_counts_match_generate_site_data(self): + bluefin, additions, unavailable = self.module.expected_counts() + data = self.module.load_generator().build(ROOT) + self.assertEqual(unavailable, data["totals"]["unavailable"]) + self.assertEqual(bluefin + additions, data["totals"]["installed"]) + # Every real gap the manifest documents is exactly the count checked -- + # this is the number that drifted (4 vs. 9) before this check existed. + self.assertEqual( + unavailable, + len(self.module.load_generator().load_installer().section( + ROOT / "packages/utah.toml", "unavailable"))) + + def test_a_stale_readme_count_is_rejected(self): + with tempfile.TemporaryDirectory() as tmp: + stale_readme = Path(tmp) / "README.md" + text = (ROOT / "README.md").read_text() + rewritten, count = re.subn( + r"Genuinely unavailable \| \*\*\d+\*\*", + "Genuinely unavailable | **4**", text) + self.assertEqual(count, 1) + stale_readme.write_text(rewritten) + + module = load_module() + module.README = stale_readme + self.assertEqual(module.main(), 1) + + def test_a_current_readme_count_passes(self): + module = load_module() + self.assertEqual(module.main(), 0) + + +if __name__ == "__main__": + unittest.main() From 53a201ff809bb21b67b31c44749d69872fd9740a Mon Sep 17 00:00:00 2001 From: Danathar Date: Mon, 21 Sep 2026 01:24:39 +0000 Subject: [PATCH 2/2] docs: fix stale installer-milestone and verification-script claims - Justfile's iso recipe comment still said installer payload integration was 'the next ISO milestone'; README now documents it as implemented and passing an offline LUKS2 install end to end (this PR's own diff). - docs/building.md credited scripts/update-e2e-readme.py for refreshing docs/verification/README.md and the root README E2E block, but iso/scripts/luks-e2e.sh writes both itself; update-e2e-readme.py is a separate CI-side script just luks-test never invokes. --- Justfile | 6 +++--- docs/building.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Justfile b/Justfile index b5f4d5e80..7bf89ea00 100644 --- a/Justfile +++ b/Justfile @@ -381,9 +381,9 @@ generate-bootable-image stream="testing": sync echo "Bootable disk ready: $disk" -# Build a single-architecture UEFI live ISO. This first slice proves the -# Utah live boot path; installer payload integration is intentionally the next -# ISO milestone. +# Build a single-architecture UEFI live ISO. `just luks-test` drives the +# bootc-installer payload this produces through an offline, LUKS2-encrypted +# install (see docs/verification); this recipe only builds the media. iso stream="testing" debug="0": #!/usr/bin/env bash set -euo pipefail diff --git a/docs/building.md b/docs/building.md index df94aff57..195aabe14 100644 --- a/docs/building.md +++ b/docs/building.md @@ -43,8 +43,8 @@ just check-repos # every contract package resolves in the enabled embedded container store with no network, unlocks the LUKS2 volume at the Plymouth prompt, confirms the disk boots on its own, and overwrites [`docs/verification/README.md`](verification/README.md) and its screenshots -with the fresh passing record (`scripts/update-e2e-readme.py`) — that file -documents exactly what a run proved and when. See +with the fresh passing record — that file documents exactly what a run +proved and when. See [`skills/local-testing.md`](skills/local-testing.md) for the encrypted and plain offline install paths and the `bootc rollback` / `uupd` update policy.