Repository navigation
docs: accuracy pass after the FSDK rebase - #276
Merged
Merged
Conversation
The OS payload is now pure FSDK 26.08 (systemd v261). Update comments in shipped elements, scripts, and tests to remove Flatcar references and explain why each workaround still exists: - /etc/resolv.conf: FSDK ships no rule (upstream systemd leaves the symlink to the distro), and /etc is empty on every boot, so the tmpfiles.d rule is still required for kubelet pod sandboxes. - firstboot credentials: the helper exists because Bluefin applies firstboot.hostname unconditionally and sets the live kernel hostname, which systemd-firstboot does not do; it is not because systemd-firstboot is missing from the image. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
patches/freedesktop-sdk/ carries six patches (0001-0006), not one. 0006 adds the Cilium/Kubernetes kernel options (VXLAN, GENEVE, tc BPF, conntrack/ss diagnostics); dropping it breaks the kubeadm and k0s sysexts. Update the verification checklist and the notes so a bumper does not drop it. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The build recipe was a forwarding alias to export-image. No doc, CI workflow, or script calls bare 'just build'. Remove it to match the avoid-over-engineering skill's rule against forwarding aliases. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
booty-integration.md: how Booty serves releases (HTTP Boot, iPXE chainload, per-node bluefin-node.ign, doInstall, kubeadm workers). secure-boot-keys.md: what each key signs (PK/KEK/DB, module cert, sysupdate signing), where keys live, how CI gets them via BOOT_KEYS_TARBALL and SYSUPDATE_SIGNING_KEY, and rotation mechanics. Index rows are deferred until projectbluefin#273 merges (it owns docs/skills/index.md). Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
files/bin/system-container was documented as shipped at /usr/bin/system-container but no element staged it. Add os-system-container.bst to install it into /usr/bin and wire it into os-stack.bst. Remove the KNOWN_UNSTAGED waiver. machinectl and systemd-nspawn ship in the base image via FSDK's systemd component, so the helper's dependencies are present. Closes projectbluefin#154 Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
castrojo
approved these changes
Sep 29, 2026
castrojo
left a comment
Contributor
There was a problem hiding this comment.
Substantive review: verified accurate documentation updates reflecting FSDK 26.08 OS architecture, cleaned up obsolete Justfile aliases, added missing documentation skills (booty-integration, secure-boot-keys), and resolved issue #154 by properly staging the system-container helper in os-stack.bst. All docs checks and full unit test suite pass.
This was referenced Sep 29, 2026
jeefy
added a commit
that referenced
this pull request
Sep 29, 2026
* docs(ci-tooling): stop pinning a literal install-action SHA in the examples The documented taiki-e/install-action SHA went stale the next time the workflows repinned. Show the pin format with a placeholder and point at build.yml for the current value, which the prose already told readers to check. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(factory-integration): drop the podman-as-sysext claim No podman sysext exists or is planned; the only container runtime we ship is containerd, inside the opt-in kubeadm sysext. Say that instead of implying podman (and other runtimes) ship as optional sysexts. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: one canonical source for the signing keys and the release publish Hard rule 6. The sysupdate-signing.asc / import-pubring.pgp pair, the gen-dev-keys behaviour, and the CI secrets were restated in ddi-installer-build.md, and the release-publishes-as-is fact was restated in both build and architecture skills. Keep the key inventory and gen-dev-keys in secure-boot-keys.md, the release-signing key in systemd-sysupdate-verification.md, and the publish contract in the ci-tooling.md release job; the build skill keeps only the rotation-needs-a-new-image-version rationale and points at the rest. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(gap-analysis-distros): trim the sources list to docs roots Section 2 already links every specific claim inline; section 6 restated the same URLs. Keep one link per distro documentation root. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: extract the offline USB installer into its own skill The installer section from #264/#268/#277 lived inside ddi-installer.md. Move it to docs/skills/usb-installer.md covering the image layout and boot flow, unattended installs through the systemd.unit-dropin.systemd-sysinstall.service credential, the firstboot root-password prompt drop-in, and provisioning the installed disk from its ESP; ddi-installer.md keeps a one-line pointer and a short artifact table row. ddi-installer.md's key and release paragraphs also collapse to pointers (the dedupe from the previous commit). Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: route booty-integration, secure-boot-keys and usb-installer All three skill files existed (or were just added) without a row in the lazy-load routing table. List them in docs/skills/index.md and in the AGENTS.md skill routing table. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(readme): add a Download a release section Point evaluators at the published artifacts before the build-oriented quick start: the GitHub Release and OCI artifact, which file covers a diskless USB boot versus an offline install versus Booty network boot, and where the verification steps live. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs accuracy pass after the FSDK rebase (#262). Fixes stale Flatcar narrative in shipped comments, corrects the FSDK patch count, removes an unused Justfile alias, adds two missing skills, and stages the
system-containerhelper that was documented but never shipped.Commits
da48e81docs: replace stale Flatcar narrative with FSDK 26.08 factsd116bdfdocs: correct patch count in bump-fsdk-version.md6b67f7cfix: remove unused Justfile build alias5643ae5docs: add booty-integration and secure-boot-keys skills6f45178fix: stage system-container helper in the base image (closes [architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element #154)Items done
Stale Flatcar narrative — updated
os-resolv-conf.bst,20-bluefin-resolv.conf,bluefin-firstboot-credentials, and two test files to explain the FSDK 26.08 reality:/etc/resolv.conf: FSDK ships no rule (upstream systemd leaves it to the distro),/etcis empty on boot, so the tmpfiles.d rule is still needed for kubelet.bluefin-firstboot-credentials: the helper exists because Bluefin appliesfirstboot.hostnameunconditionally and sets the live kernel hostname, not becausesystemd-firstbootis missing.os-creds-prov.bstis owned by fix(security): ship root locked; provision access per node #275 and already fixed there; skipped.bump-fsdk-version.md patch count — corrected from "one patch remains" to six patches, with a warning that
0006carries the Cilium/Kubernetes kernel options and must not be dropped.Justfile
buildalias — deleted. No doc, CI workflow, or script calls barejust build.New skills — created
docs/skills/booty-integration.mdanddocs/skills/secure-boot-keys.md. Index rows deferred until feat(initrd): explain diskless boot failures and ignored Ignition kargs #273 merges (it ownsdocs/skills/index.md).Issue [architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element #154 — staged
files/bin/system-containerin the base image via newos-system-container.bst.machinectlandsystemd-nspawnship in the base image via FSDK's systemd component, so dependencies are present. Removed theKNOWN_UNSTAGEDwaiver.Items deferred (blocked by open PRs)
signing-and-sbomrefcoreuser refdocs/skills/usb-installer.mdFollow-up after #273 merges
Add rows to
docs/skills/index.mdfor:booty-integration.mdsecure-boot-keys.mdusb-installer.md(after extraction from ddi-installer.md)Verification
python3 .github/scripts/docs-checks.pypassespytest tests/unit/passes (372 passed)bats tests/unit/passes