Roadmap
Last updated: 2026-10-08 | Maintainer: tuna-os (hanthor)
Mission
bootc-installer is the org's install front door: the monorepo for every
TunaOS / Bluefin installer frontend. Five frontends (GNOME at the root; KDE,
COSMIC, Niri and XFCE under frontends/) render one shared screen contract
and write one shared recipe for the fisherman Go backend, which executes the
install pipeline (partition → format → LUKS → mount → bootc install →
post-install → finalize) on both the systemd-boot/UKI stack (Dakota) and the
GRUB2 stack (Bluefin, Bluefin-LTS, Bazzite). The recipe sets which stages run.
Architecture principle
Shared code is shared. A frontend contains only what it needs to feel native on its desktop: its widgets, its layout, its desktop integration.
- Logic goes in fisherman. All five frontends already run fisherman, so a rule that fisherman computes is computed once. Examples: validation, progress percentages, disk facts, failure reports. A frontend asks fisherman and shows the answer.
- Contracts and data go in
shared/. The recipe schema, branding and copy, the screen contract, test fixtures and translations. A frontend reads them through one thin per-language reader. - A frontend owns only native UI. If two frontends implement the same
rule, that rule moves to fisherman or
shared/, and a test fails when a frontend re-implements it.
Every item below is judged against this principle. A feature that needs logic
lands in fisherman or shared/ first; the frontends then only render it.
Current status (measured 2026-10-08)
The repository changed shape on 2026-09-17. Four separate frontend
repositories (tuna-installer-kde|cosmic|niri|xfce) were imported with
git subtree add and frozen; they no longer resolve on GitHub. What used to
be a cross-repo parity goal is now an in-repo property, measured in CI. The
record of the move, and every issue and PR it carried over, is
docs/MIGRATION.md (epic #83, closed).
| Area | State | Evidence |
|---|---|---|
| Frontend parity | All five frontends reach all six contract screens (welcome, disk, encryption, summary, install, done). | docs/walkthrough/README.md, regenerated by CI from real screenshots; docs/PARITY.md for the per-key rendering table |
| Shared core | Recipe schema, parity report and walkthrough aggregator live in shared/; KDE and COSMIC still vendor copies, drift-checked in CI. | docs/MIGRATION.md "shared/" |
Validation on dev | Flatpak, Python, Go, per-frontend Flatpak, screenshots ×5, end-to-end (every frontend drives fisherman to a booted VM), walkthrough: all green on 44561ead (#202). | Actions on dev |
| Promotion | promote.yml fast-forwards prod from dev when every check is green; prod was last promoted on 2026-10-08 (44561ead, #202). | docs/RELEASE.md |
| Publishing | GNOME only. release.yml failed on every prod run from 09-18 to 09-25; #145 fixed it and the 09-26 run (v2026.09.26-253d6938) published GNOME. The served index lists org.bootcinstaller.Installer under tuna-os/bootc-installer, but KDE, COSMIC, Niri and XFCE only under the orphaned pre-migration entries tuna-os/tuna-installer-* (images from 09-17/18), which no workflow updates. | #158; #100 and #107 closed |
| Browser rendering | New direction landed 09-19: the two GTK frontends render in a browser through Broadway and are driven by Playwright (#102). Niri (#103), KDE (#104) and COSMIC (#105, working, five patches to send upstream to libcosmic) follow. | shared/browser/ |
Priorities
| Priority | Item | Tracking | Status |
|---|---|---|---|
| P0 | Publish KDE, COSMIC, Niri and XFCE under tuna-os/bootc-installer and retire the orphaned tuna-installer-* index entries | #158 | 🔴 Open |
| P0 | Live-ISO flow documented and tested end to end | docs/live-iso.md, e2e.yml | 🟢 e2e runs every push; docs exist |
| P1 | Finish the shared core: KDE and COSMIC consume shared/ instead of vendored copies | docs/MIGRATION.md | 🟡 Drift-checked, not yet consolidated |
| P1 | Browser rendering for the three non-GTK frontends | #103, #104, #105 | 🟡 COSMIC renders; Niri and KDE open |
| P1 | Per-frontend ROADMAP.md files under frontends/ still describe standalone repositories and cite issue numbers from the deleted repositories | #112 | ⬜ Not started |
| P2 | One version identity: meson.build says 3.0.0, VERSION says 1.0.0, tags carry both legacy v3.0.x and the authoritative vYYYY.MM.DD-<sha> from RELEASE.md | docs/RELEASE.md | ⬜ Not started |
| P2 | Docs guidebook and a slimmed README; the automated walkthrough half of the ask is done | #84 | 🟡 Walkthrough exists |
| P3 | Record what has been sent upstream to the Vanilla OS installer and what is fork-only | #23 | ⬜ No record |
Quarterly goals
2026 Q3 (July–September) — closing
Theme was: stable, token-safe install UX. What actually happened was larger: the monorepo consolidation.
| Goal | Tracking | Outcome |
|---|---|---|
| No secrets in recipe or clone paths | #12 | ✅ Done |
| Baseline CI green on both boot stacks | #11, e2e.yml | ✅ Done; e2e now boots every frontend's recipe in a VM |
| Publish install-UX guide for tunaos.org | #84 | 🟡 Walkthrough generated; guidebook not written |
| Define tuna-installer-* parity contract | #83 | ✅ Superseded: frontends merged, contract lives in shared/ and is measured per push |
2026 Q4 (October–December)
Theme: five installers that ship, from one repository.
- Flatpak remote carries all five frontends under one index entry, published only by promotion (#158); the docs smoke test stays green for a full month.
- Signed Flatpak releases and SBOM aligned with the org supply-chain work (tunaos#1187).
- LUKS-first and dual-boot scenarios validated on the RHEL track (tunaos#1123).
- Browser rendering for all five frontends, so every frontend can be tested and demonstrated without a desktop session (#102–#105).
shared/is the only copy of the recipe schema and parity report.- Per-frontend roadmaps either folded into this file or rewritten for the monorepo.
- Recovery and rollback path documented.
Consolidation plan
An audit on 2026-10-08 found the same non-UI logic in all five frontends. The copies that no shared fixture pins have drifted, and some drift is a bug. This plan moves that logic out of the frontends. Each fisherman step is additive, so older frontends keep working until they switch.
| Step | Moves to | What each frontend deletes | Bugs it removes |
|---|---|---|---|
| F1 Progress | fisherman emits overall_pct and step_id on every event; labels become step_* copy keys | its milestone table, layer regex and bar maths (about 70–125 lines each) | the bar stops during the Flatpak step; Niri shows raw step names; KDE and COSMIC hard-code the title |
F2 fisherman probe --json | fisherman: disks, TPM, RAM, CPU, UEFI, live image, offline stores | lsblk parsing, size formatting, TPM probe, readiness checks | five different disk filters (zram and the live USB are offered in three); three size units; Niri never shows the disk model; only GNOME checks RAM, CPU and UEFI |
| F3 Recipe handling | fisherman finds offline stores on the host, rejects an empty image when not live, reads the recipe from stdin | offline and live detection, temp recipe files (about 390 lines) | four frontends look for offline stores inside the Flatpak sandbox; GNOME treats any ostree host as live |
F4 fisherman validate --json | fisherman: hostname, username, filesystem and encryption rules; shared/recipe/encryption-choices.json | validation code and the encryption choices table | a bad username fails after the OS is on disk; only XFCE checks the hostname |
| F5 Log and BootNext | fisherman writes the log (mode 0600, recovery key redacted) and sets BootNext | log code and the reboot boot-entry call | five log formats, all with the recovery key in plain text; GNOME runs efibootmgr without root |
F6 fisherman images --json | fisherman resolves the image catalog | catalog readers (about 285 lines) | needs_user_creation defaults differ; XFCE drops @alias flatpaks |
| F7 Hostname suggestion | fisherman hostname --suggest | GNOME's DMI code | four frontends give every machine the same hostname |
| F8 Branding | fisherman branding --json | four resolvers (about 1,100 lines) | low risk today: fixtures pin all four |
Fixes that need no fisherman change land first: the KDE stream buffer and the
COSMIC stderr read order, the schema's distroID default, XFCE's filesystem
default, GNOME's TPM switch, the Niri disk model, one shared readiness.py,
and the KDE rows in docs/PARITY.md.
When a step lands, a test fails if a frontend still carries its own copy.
F2 status (2026-10-09): frontends switched. fisherman#268 ships the probe.
All five frontends read their disks, TPM and RAM/CPU/UEFI facts from it
(shared/probe/README.md), and the five disk filters, three size units and
two TPM probes are gone. tests/unit/test_shared_probe.py fails if a frontend
runs lsblk to list disks, and tests/unit/test_shared_tpm.py fails if one
probes the TPM. The probe's live-image and offline-store facts are not used
yet; F3 moves them.
F3 status (2026-10-15): frontends switched. fisherman#276 reads the
recipe from stdin and finds the offline stores on the host. It rejects an
empty image off live media. All five frontends pipe the recipe to
fisherman - and write no recipe file; none looks for live media or
offline stores itself. Live media and the "available offline" tags come
from the probe's live and offline sections. A frontend writes
additionalImageStores only when the ISO's recipe names stores.
tests/unit/test_no_frontend_detection.py fails if a frontend detects
either again or writes a recipe file.
F4 status (2026-10-15): frontends switched. fisherman#277 adds
fisherman validate --json [--partial] and data/encryption-choices.json.
Each frontend checks its fields with validate --json --partial - while
the user types and shows each problem through a validate_<code> copy key:
the hostname in all five (new for GNOME, COSMIC and Niri), the username in
GNOME and XFCE, the passphrase in KDE, COSMIC, Niri and XFCE. The
in-frontend hostname, username and passphrase-required rules are gone;
password strength and confirmation stay in the frontends.
shared/recipe/encryption-choices.json is fisherman's file byte for byte;
KDE, COSMIC, Niri and XFCE read a copy of it and use needs_passphrase and
needs_tpm2 instead of the type's name.
Planned features
The maintainer approved these on 2026-10-08. They are not scheduled yet. "fisherman" means the work is in the backend repository; the other items are in this repository.
Safety and recovery
| Feature | Where | What it fixes |
|---|---|---|
| Clean cancel and kill handling | fisherman | fisherman has no signal handler. A cancelled or killed install leaves mounts and LUKS mappings behind and emits no error event. Unmount, close the mappings and emit error. |
| Durable data-migration rescue | fisherman | Before partitioning, copy the selected user data to persistent storage, so a failed install cannot lose it. Requested migration stays off until this exists (fisherman draft #245). |
| Recovery key export | all frontends | On the done page, show the TPM recovery key as a QR code and offer to save it to a USB stick. Today the key is only on screen. |
| Failure report bundle | all frontends | After a failed install, one button saves the fisherman log, the recipe without the passphrase, and hardware facts to one file for a bug report. |
Installer features
| Feature | Where | What it fixes |
|---|---|---|
| Manual partitioning in every frontend | KDE, COSMIC, Niri, XFCE | Bring GNOME's custom-mount layout to the other four, through fisherman's existing customMounts. Depends on fisherman #266 for a correct progress bar. |
| Existing-disk preview | all frontends | Before the erase warning, list what is on the target disk: partitions, sizes and detected operating systems. |
| Shared translations | shared/, all frontends | Move every user-facing string into the shared copy layer with gettext catalogs, so one translation covers all five frontends. |
| Progress-protocol version handshake | fisherman, all frontends | fisherman reports a protocol version. A frontend refuses, with a clear message, a fisherman too old for the events it uses. |
Testing
| Feature | Where | What it fixes |
|---|---|---|
| Boot with SELinux enforcing | shared/e2e/ | Label the SSH test files, then stop patching enforcing=0 into the boot entries. CI then proves that installs boot with SELinux enforcing. |
| Browser click-through for KDE and COSMIC | shared/browser/ | Finish the KDE wasm build (#104, PR #169) and find a route for COSMIC (#105), so a browser clicks through all five frontends. |
Encrypted installs (LUKS passphrase and TPM2) already have end-to-end tests
in projectbluefin/dakota-iso and tuna-os/tunaos. This repository does not
duplicate them.
Release and distribution
| Feature | Where | What it fixes |
|---|---|---|
| Tagged fisherman releases | fisherman | Semver tags and a changelog, so this repository and wootc pin releases, not drifting commits (fisherman #205; wootc's pin is 94 commits behind). |
| Automatic fisherman pin bump | this repository | When fisherman's dev passes CI, open a submodule-bump PR here, so backend fixes reach the installers without a manual step. |
| Published-build freshness check | .github/workflows/ | A daily job compares each frontend's served Flatpak with prod and opens an issue when they differ. This catches problems like #158 within one day. |
| Release notes per frontend | release.yml | Group each release's notes by frontend and backend from PR labels, so each desktop's users see what changed for them. |
Technical debt backlog
| Item | Issue | Priority |
|---|---|---|
| Progress view owns privileged execution and UI lifecycle | #80 | P1 |
| Host execution policy fragmented across GTK and core modules | #82 | P1 |
| Disk wizard collapses six boundaries into one GTK module | #85 | P1 |
| Frozen KDE repository retains a second live publication authority | #106 | P1 |
| Committed OSTree store (17,364 objects) still in git history | #62 | P2 |
How to contribute
See CONTRIBUTING.md and AGENTS.md. PRs target
dev; prod is only ever written by promotion. Good entry points: the
non-GTK browser harnesses (#103, #104), folding the vendored KDE and COSMIC
copies into shared/.
Roadmap governance
Updated after major milestones or quarterly. Propose changes via PR to this file with an issue reference; every status claim should point at a workflow, a document or an issue that a reader can check.