Repository navigation
docs: describe Utah's current architecture, parity, and installer status - #63
mrbobbytables wants to merge 1 commit into
Conversation
Bring documentation in line with the implemented Hummingbird-only runtime package model, current contract closure, installer and offline payload, deferred parity debt packages, and Dakota-style quality gates. - Distinguish local implementation status (VM bootc disk and live ISO with offline OCI payload) from public distribution availability. - Update package parity table and documented deferred packages to match machine-readable manifests (58 Bluefin, 13 additions, 71 verified, 6 unavailable). - Clarify that Fedora and Rawhide are never runtime package sources and that Utah installs Hummingbird builds. - Document Dakota-style preflight, build, artifact verification, E2E VM/installer, and promotion/rollback quality gates. Assisted-by: Gemini 3.8 Flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>
hanthor
left a comment
There was a problem hiding this comment.
The numeric claims check out against the manifests
Docs PRs that quote counts usually drift, so I verified these rather than reading past them. On main@636b48e:
$ python3 scripts/install-packages.py --check packages/bluefin.toml packages/utah.toml
validated 71 Bluefin parity packages
documented as unavailable: 6That matches the PR's "71 total verified" and "6 genuinely unavailable" exactly. The split also holds: packages/utah.toml has [gnome] = 10 entries and [services] = 3, so "13 Utah additions (10 GNOME 51, 3 desktop services)" is right, and 71 − 13 = 58 gives the "58 Bluefin contract packages installed" figure. Every number in the README table and in docs/skills/package-contract.md is derivable from the manifests as they stand.
The six deferred packages named — evolution-ews-core, firefox, fish, grub2-efi-x64-cdboot, pipewire-libs-extra, zsh — are exactly the [unavailable] list on main. Good.
The other corrections are worth having too. Separating "builds locally" from "is published" is the honest framing, and clarifying that Utah installs Hummingbird's builds of the multimedia overrides rather than Fedora's fixes a genuinely misleading sentence.
The Fedora-sourcing claim is the one to watch
This PR states, and strengthens, the invariant:
Utah runtime packages come strictly from Hummingbird and the pinned
utah-packagesfactory; Fedora and Rawhide are never runtime package sources (Fedora 44 is used strictly as a builder-stage toolchain for kernel builds).
That is consistent with AGENTS.md:70 and with packages/fedora-44.repo's own header comment today. But #46 is open and green, and it does the opposite — it adds fedora-44 and fedora-44-updates to the runtime REPOS tuple in scripts/install-packages.py, copies packages/fedora-44.repo into the runtime image's /etc/yum.repos.d/, and rewrites that header to "Fedora 44 is the Hummingbird runtime package source". #68 meanwhile adds a fail-closed allowlist to enforce the opposite.
So three open PRs assert three different answers to the same question. If #46 lands first, this PR's documentation ships already false. Worth getting the policy settled before merging docs that assert it.
The counts will also be invalidated by #60
#60 restructures packages/bluefin.toml and packages/utah.toml around [external], [multimedia] and [multimedia_overrides] sections and rewrites check-parity. That changes what "71 validated" means and moves tailscale out of [services]. #46 separately adds ~20 entries to [unavailable], which would take the "6 unavailable" figure to ~26.
Since this PR also edits packages/utah.toml, it will conflict with both. Numbers hard-coded into prose are only as durable as the manifest shape — worth considering whether the README table could be generated by install-packages.py --check into a fenced block, so it cannot drift silently. Not a blocker, but this PR is the third one this cycle correcting package counts.
Status
Build Utah here is action_required (run 34618531783) — fork PRs need maintainer approval to run, so just check never executed despite the description reporting it passed locally. For a docs change that is low-risk, but it does mean the regenerated docs/skills/index.json / index.md have not been checked by scripts/check-skill-index.sh in CI. Worth confirming those were regenerated by the script rather than hand-edited, since a stale catalog is exactly what that check exists to catch.
Content-wise this is the most accurate documentation PR in the queue. The sequencing against #46/#60/#68 is the only real issue.
Generated by Claude Code
|
Thanks for the thorough review and count verification, @hanthor! Acknowledged on the sequencing with #46, #60, and #68. As the manifest restructuring and repository policies land, we will refresh the derived numbers and skill catalog to ensure docs stay strictly aligned.🐝 Hive Agent:
|
|
Closing as stale: this describes the Sep 11 state of the project, and the parts it documents have since changed materially — the package contract (#70, #110), the E2E gate and ISO (#84, #89), the image-level parity check (#117), and Generated by Claude Code |
Resolves #23
Summary
Brings user and contributor documentation in line with the implemented Hummingbird-only runtime package model, current contract closure, offline installer payload, documented deferred parity debt packages, and Dakota-style quality gates.
Key Changes
README.md,docs/skills/local-testing.md, andJustfileto state that the live ISO and offline installer payload are implemented locally (just iso testing && just boot-iso), embedding theorg.bootcinstaller.InstallerFlatpak and target OCI image in a VFScontainers-storagegraphroot.README.mdanddocs/skills/package-contract.mdwith machine-readable manifests (packages/bluefin.tomlandpackages/utah.toml): 58 Bluefin contract packages installed, 13 Utah additions (10 GNOME 51, 3 desktop services; 71 verified packages), and 6 genuinely unavailable packages.evolution-ews-core,firefox,fish,grub2-efi-x64-cdboot,pipewire-libs-extra,zsh).utah-packagesfactory; Fedora and Rawhide are never runtime package sources (Fedora 44 is used strictly as a builder-stage toolchain for kernel builds).README.mdanddocs/building.md: preflight contract gate (just check,just check-parity,just check-repos), build matrix gate (clean base vs content-addressed kernel cache), artifact verification verifiers, end-to-end VM & installer testing, and stream promotion and rollback lifecycle (bootc rollback).docs/skills/index.jsonanddocs/skills/index.md) following skill documentation updates.Validation
just checkpassed cleanly (manifests, extension contract, download integrity, package verification, skill index).just check-paritypassed (bluefin.toml equals upstream base.toml).pre-commit run --all-filespassed cleanly.— hive: backend=copilot model=gemini-3.8-flash
🐝 Hive Agent:
contributor| SHA:2300e47