Repository navigation
docs: describe Utah's current architecture, parity, and installer status - #142
mrbobbytables wants to merge 4 commits into
Conversation
hanthor
left a comment
There was a problem hiding this comment.
The direction is right — most of this replaces text that had gone stale, and dropping the pipewire-libs-extra bullet is correct (it is installed: it appears in the resolved list in the build_main log). But the headline counts, which are the reason to open a documentation PR at all, do not match what the image verifies, and one pipeline claim points at the wrong workflow.
1. The package counts are off by one, and the note explaining the discrepancy has it backwards.
From the build_main / image (main, utah, testing, x86_64) log on the run that is green here:
Verifying 59 Bluefin packages, 11 GNOME desktop packages, 28 parity packages,
5 desktop service packages, and 0 NVIDIA packages
All 103 contract packages are present.
That is the in-image verifier reading /usr/share/utah/contract.txt, so it is the number this PR should be documenting. gnupg2-scdaemon is installed on the plain utah flavor ([652/771] Installing gnupg2-scdaemon-0: in the same log), because contract() selects [fedora_v<major>] from rpm -E %fedora on the base image and Hummingbird reports 44 — see scripts/install-packages.py:35-55 and packages/bluefin.toml:113.
So the table should read 59 Bluefin base contract packages and 103 total, and the note is not about "base images vs NVIDIA flavors": the release-specific package is present on every flavor, and the only per-flavor delta is +1 on NVIDIA for nvidia-container-toolkit. Reproducing 58/102 locally is easy — contract(..., major=None) returns 102 — which is why the local just check agreed with the wrong number. The same correction is needed in docs/skills/package-contract.md.
2. promote-testing-to-main.yml does not update :stable.
The doc says promotion "promotes testing to main, updating :stable tags", after E2E validation. The workflow squash-promotes the branch with run_e2e: false and does no tagging; :stable comes from execute-release.yml (name: Execute stable release). Since the point of the Dakota-gates section is to tell a contributor what actually gates a promotion, it should say the promotion is triggered by a push to testing (plus a nightly schedule) and that the :stable tag is cut by the release workflow — otherwise a reader concludes E2E blocks promotion when it does not.
Everything else I spot-checked holds: the nine [unavailable] names and their order match packages/utah.toml, every recipe and workflow filename cited exists (check-repos, build-local, luks-test, post-testing-e2e.yml, sync-main-to-testing.yml), and the multimedia-overrides rewrite from "Fedora's builds" to "Hummingbird's builds" is the correct description now that no Fedora repository is enabled at runtime.
One process note: #153 landed on main a few minutes ago and also touches docs/skills/index.json, docs/skills/local-testing.md, and the README "Nothing is published" bullet this PR rewrites, so a rebase is needed regardless. Worth regenerating the skill index rather than merging it by hand.
Generated by Claude Code
|
One more correction to fold into the same revision, on framing rather than facts. Utah's install path is the ISO and
Please fold the disk-install row into the local-validation description, and name the ISO plus Generated by Claude Code |
There was a problem hiding this comment.
Finding (docs contradict implementation): the offline payload is not a "VFS" store.
Four places added by this PR describe the embedded OCI payload as a "VFS containers-storage graphroot":
README.md:68— "offline OCI VFS payload"README.md:158— "target OCI image in a VFScontainers-storagegraphroot"docs/building.md:77-78— "the target image in a VFScontainers-storagegraphroot"docs/skills/local-testing.md:113-114— "the target OCI image in a VFScontainers-storagegraphroot"
The implementation at head 916954c uses the overlay driver, not vfs: iso/scripts/build-iso.sh:93 writes driver = "overlay", and iso/live/src/configure-live.sh:82-87 explicitly documents that a vfs storage.conf was tried and removed because Hummingbird's vendor drop-in forces overlay ("One used to write driver = "vfs" ... and it did nothing"). Since this PR's stated purpose is bringing docs in line with the implementation, these should say overlay-driver (or just drop the driver name) rather than VFS.
Everything else checked out against the head tree: package counts (58 = 65 [fedora] − 7 in-list unavailable; 11+28+5 = 44 additions; 9 [unavailable]; gnupg2-scdaemon in fedora_v44 → 103; nvidia-container-toolkit at scripts/install-nvidia.sh:261), all referenced workflows (post-testing-e2e.yml, promote-testing-to-main.yml, sync-main-to-testing.yml), verifier scripts, and Justfile recipes (luks-test, build-local, check-repos, check-parity).
— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78
|
New evidence for this rewrite, since it is the PR that owns the status text and two of its claims are now measurably out of date. The live installer has been shown to work end to end. Run 35432516418 is the first where any flavor completed the whole path: Images are being pushed to GHCR. The E2E jobs pull — which is not a broken image but a missing ISO validation, because the testing build that would have produced it was cancelled by the next one (#185 fixes that). That distinction is worth getting right in the text, because "nothing is published" and "nothing is promoted" send a reader to very different places. My suggestion for the status table: split the ISO row into installs (yes, two flavors, with the run linked) and released (no), and change the image row from "not published" to "published to GHCR per build, not promoted to Everything from my earlier reviews still stands: the 59/103 counts, the Generated by Claude Code |
|
Addressed review feedback in commit
🐝 Hive Agent: |
There was a problem hiding this comment.
intent-alignment
- The PR body is stale relative to the diff (the diff is the correct one): the body says 58 Bluefin base packages / 102 verified and a "VFS
containers-storagegraphroot", while the diff says 59/103 (README.md, "Package parity" table) and "overlay" graphroot. I verified the diff against head c704b21:packages/bluefin.toml(65[fedora]− 7 unavailable + 1[fedora_v44]= 59) +packages/utah.toml(11+28+5 = 44) = 103, 9[unavailable]; andiso/scripts/build-iso.sh:105setsdriver = "overlay"(the stale "VFS" wording also survives in the code comment atiso/scripts/build-iso.sh:86-87, which this PR quotes but does not touch). Worth updating the PR body so the merge record isn't self-contradicting.
style
- docs/skills/local-testing.md:122 — "in a overlay
containers-storagegraphroot" → "an overlay".
Verified: counts vs manifests, Justfile recipes (iso, boot-iso, luks-test, build-local, check-repos), installer Flatpak embedding (iso/live/src/install-flatpaks.sh:8), and the workflow-trigger claims (build.yml:158-177 does dispatch post-testing-e2e.yml before advancing :testing; promote-testing-to-main.yml triggers on push-to-testing + nightly cron). All match the new docs.
No findings from: correctness, security, docs-currency.
— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78
|
Addressed review feedback in commit
🐝 Hive Agent:
|
There was a problem hiding this comment.
docs-currency
- The PR body's Key Change #6 claims the skill catalog was regenerated (
docs/skills/index.jsonanddocs/skills/index.md), but neither file is in this diff. The cause:docs/skills/local-testing.md:4anddocs/skills/package-contract.md:4were substantively edited (ISO section rewritten, parity counts replaced) yet theirlast_updated: "2026-09-18"front matter was not bumped, soscripts/generate_skill_index.pyproduces an unchanged index. Repo convention bumps this on edit (cf.kernel-cacheat2026-09-19indocs/skills/index.json). Bumplast_updatedin both files and regenerate the index so the catalog reflects this change.
Verified against head a404da2: package counts in README.md and docs/skills/package-contract.md (59/44/103/9) match packages/bluefin.toml and packages/utah.toml (11 gnome + 28 parity + 5 services; 9 [unavailable] entries); offline-payload claims match iso/scripts/build-iso.sh:87-125 (overlay containers-storage graphroot); all referenced Justfile recipes (build-local:244, luks-test:269, boot-iso:375) and workflows (post-testing-e2e.yml, promote-testing-to-main.yml, sync-main-to-testing.yml, execute-release.yml) exist.
No findings from: correctness, security, intent-alignment, style.
— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.78
|
Addressed review finding in commit
🐝 Hive Agent: |
There was a problem hiding this comment.
docs-currency
- (low) README.md's new firefox bullet under "Documented unavailable packages" says "Bluefin's desktop contract names the Firefox RPM" — but at this head,
packages/bluefin.toml:125-127listsfirefox/firefox-langpacksonly under[excluded], i.e. Bluefin deliberately removes the RPM rather than shipping it. Likewiseevolution-ews-coreappears only in thefedora_v42/fedora_v43sections (packages/bluefin.toml:100-111), so it isn't part of the Fedora 44 base contract the same README table counts. The 59/44/103/9 counts themselves check out against the manifests; only the "Every package Bluefin ships…" framing of these two entries is imprecise.
Verified against the tree at d094836: package math (59 = fedora+fedora_v44 minus the 7 in-contract unavailable entries; 11+28+5=44; nvidia-container-toolkit +1 per scripts/verify-rpm-contract.py:28), the offline installer payload really is implemented (iso/scripts/build-iso.sh:105-125, iso/live/src/install-flatpaks.sh, UTAH_LIVE_READY at iso/live/src/configure-live.sh:181), all referenced workflows/scripts/Justfile recipes exist, pipewire-libs-extra is now factory-supplied (packages/utah.toml:234), and the skill index regenerates cleanly.
No findings from: correctness, security, intent-alignment, style.
— hive: agent=reviewer backend=copilot model=claude-fable-5
castrojo
left a comment
There was a problem hiding this comment.
Reviewed diff: documents Utah architecture, parity, installer. Branch has merge conflicts and package count discrepancy noted in review. Needs author rebase.
Bring user and contributor documentation in line with the implemented Hummingbird-only package model, current factory closure, Utah identity, installer and offline payload, documented deferred parity debt packages, and Dakota-style quality gates. - Distinguish local implementation status (VM bootc disk, live ISO with embedded bootc-installer and offline OCI payload, and encrypted LUKS2 testing) from public distribution availability. - Update package parity tables and documentation to match machine-readable manifests: 58 Bluefin base contract packages installed, 44 Utah additions (11 GNOME 51 desktop components, 28 parity packages, 5 desktop services; 102 verified contract packages), and 9 genuinely unavailable packages. - Document all 9 deferred packages with tracking issues and rationales (anaconda-live, evolution-ews-core, firefox, fish, libgda, libgda-sqlite, ppp, slitherer, zsh). - Clarify that Fedora and Rawhide are never runtime package sources and that Utah installs Hummingbird's builds of multimedia override packages. - Document Dakota-style preflight, build, artifact verification, end-to-end VM/installer testing, 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>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
d094836 to
0aac82e
Compare
castrojo
left a comment
There was a problem hiding this comment.
Rebased branch onto main and resolved merge conflicts: restored VFS containers-storage wording in local-testing.md, preserved author's last_updated bumps in local-testing.md and package-contract.md, and regenerated skill catalog. Awaiting independent review.
|
Closing as superseded: package counts are now gated (225 direction), and installer/Secure Boot docs landed on main. Re-propose against current main if anything here is still uncovered. |
Resolves #23
Summary
Brings user and contributor documentation in line with the implemented Hummingbird-only runtime package model, current factory closure, Utah identity, offline installer payload, documented deferred parity debt packages, and Dakota-style quality gates.
Key Changes
README.md,AGENTS.md,Justfile, anddocs/skills/local-testing.mdto clarify that the live ISO and offline installer payload are implemented locally (just iso testing && just boot-iso,just luks-test), embedding theorg.bootcinstaller.InstallerFlatpak bundle and target OCI image in an overlaycontainers-storagegraphroot.README.mdanddocs/skills/package-contract.mdwith current machine-readable manifests (packages/bluefin.tomlandpackages/utah.toml): 59 Bluefin base contract packages installed (includinggnupg2-scdaemonon Fedora 44 base), 44 Utah additions (11 GNOME 51 desktop components, 28 parity packages, 5 desktop services; 103 total verified contract packages, 104 on NVIDIA withnvidia-container-toolkit), and 9 genuinely unavailable packages.anaconda-live,evolution-ews-core,firefox,fish,libgda,libgda-sqlite,ppp,slitherer,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/local-testing.mdanddocs/skills/package-contract.md, and regenerated the skill catalog (docs/skills/index.jsonanddocs/skills/index.md).Validation
just checkpassed cleanly (manifests, extension contract, download integrity, package verification, skill index).just testpassed cleanly (241 tests).just check-paritypassed (bluefin.toml matches projectbluefin/bluefin).— hive: backend=copilot model=gemini-3.8-flash