Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -378,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
Expand Down
36 changes: 22 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -60,22 +65,28 @@ 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`).



## Known gaps

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
Expand All @@ -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
Expand Down
23 changes: 23 additions & 0 deletions docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 — 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 |
Expand Down
9 changes: 6 additions & 3 deletions docs/skills/package-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
```
91 changes: 91 additions & 0 deletions scripts/check-doc-counts.py
Original file line number Diff line number Diff line change
@@ -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())
69 changes: 69 additions & 0 deletions tests/test_check_doc_counts.py
Original file line number Diff line number Diff line change
@@ -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()
Loading