release rollback
docs/release.md covers cutting a release. This covers what to
do once one is already tagged, built, or published and turns out to be
wrong — a regression caught after the tag, a .deb that fails on a target
it was supposed to support, or a Marlin image digest that shouldn't have
been promoted.
There is no automated rollback. scripts/tuna-release and
.github/workflows/baseline.yml only build and publish forward; nothing in
this repository un-publishes a release or repoints a tag. The steps below
are the manual recovery path, ordered by how far the bad release already
traveled.
1. Confirm it's actually bad before touching anything
Check what's already live:
gh release view vX.Y.Z— is the.deb, notes, and walkthrough media attached? Has anyone downloaded it (gh release view vX.Y.Z --json assetsincludes download counts)?- Does
docs/walkthrough.mdonmainalready point at this tag's media? (Step 9 of the release checklist commits this separately from the tag push, so a release can be tagged and even packaged without the docs site referencing it yet — check before assuming public visibility.) - Is the regression in the GTK shell/compositor itself, or only in packaging (missing dependency, wrong binary, bad metadata)? This decides whether you need a new build or just a corrected package.
If nothing has been downloaded and the walkthrough page doesn't reference the tag yet, you likely only need step 2 (delete) and a corrected re-release under the next patch version — skip straight there.
2. Pull the published artifact
gh release delete vX.Y.Z --repo tuna-os/tuna-desktop
This is reversible up to the point someone already has the .deb — the
release metadata and asset can be recreated, but you cannot force an update
on whoever already downloaded and installed it. Do this first regardless of
how far the bad release traveled, so no one else picks it up while you work
out the rest.
Do not delete or move the git tag itself yet (see step 4) — the release
and the tag are separate; gh release delete removes the GitHub Release
object and its assets, not refs/tags/vX.Y.Z.
3. Decide forward-fix vs. tag surgery
Default to a forward fix: cut vX.Y.Z+1 (or the next patch) with the
regression fixed, following the normal checklist in
docs/release.md. This is almost always correct — the tag
history stays truthful, and scripts/tuna-release's version-stamp
enforcement and the visual-review gate (docs/reviews/vX.Y.Z.md) both
assume tags are append-only.
Only consider moving or deleting the git tag itself (git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z) if the tagged commit is actively
harmful to publish under any version — e.g. it leaked something it
shouldn't have, or the visual review was filled in incorrectly and the
TBD-check in tuna-release was bypassed with --allow-dirty by mistake.
Tag deletion is harder to reverse once anyone has fetched it (git fetch --tags on a clone that already has it won't drop it locally), and it
breaks git describe for anyone who built from that commit. If you do
delete a tag, say so in the release notes for the replacement version so
the gap in the sequence is explained rather than silently skipped.
4. If the bad build reached a Marlin image
A signed Marlin image promotion is a separate, heavier-weight publish than
the .deb (see item 3 in the public roadmap — update/rollback
evidence for the admitted image is explicitly tracked as still-open
qualification work, not yet a solved problem). If a bad Tuna Desktop
package made it into a promoted Marlin image digest:
- Do not try to hand-patch the running image. Treat this the same as any other bad Marlin promotion and follow whatever rollback path the image pipeline that promoted it documents (that pipeline, not this repository, owns the bootc image's own rollback — check its runbooks, not this one).
- File or update an issue here noting which Tuna Desktop tag was in the bad digest, so the image-side rollback can cite the right component version when writing its own incident notes.
- For the user,
sudo bootc rollbackand a reboot return to the previous deployment. upgrade-recovery.md is the proof that this keeps their home, settings and shell state for a given pair of digests; run it on the previous image and the candidate before promoting.
5. Update the public-facing trail
- Regenerate
walkthrough-media/walkthrough.mdfor the replacement tag:scripts/tuna-capture --artifacts walkthrough-media --render-walkthrough vX.Y.Z+1, then upload it with that release's replacement media and update the release-notes link. Do not stamp release links into the canonicaldocs/walkthrough.md; its manifest-generated feature tour has a separate visual capture workflow. - Add a line to the replacement version's release notes under "Known limitations" or a new "Corrections" heading naming what was wrong with the withdrawn tag, so the gap in the version sequence has a public explanation instead of looking like a skipped number.
- If the regression reached users before being caught (not just caught in review before download), consider whether it needs an entry in docs/parity-ledger.md — a shipped-then-reverted regression against a GNOME 51 behavior is exactly what that ledger tracks, and it's easy to forget once the fire is out.
What this does not cover
- Crash recovery at runtime (shell restart budgets, the recovery overlay,
disconnect/reconnect, stale-revision snapshots) is a different problem:
the recovery contract in
crates/compositor/tests/recovery.rs, and on the published image the crash steps of upgrade-recovery.md. This document is about recovering from having published the wrong build in the first place. - The Debian/Ubuntu package
.debrollback above does not apply to the Marlin bootc image's own update/rollback mechanism; its user-state proof is upgrade-recovery.md.