kittymux

Release checklist

What must be true before you announce a release, what is still open, and the claims to avoid. Early-adopter ready is the honest state today.

The honest state today is early-adopter ready, not ready for every terminal. Tick these before announcing. An unchecked item is not done.

Must: a stranger can install it and it works

  • install.sh is idempotent, backs up kitty.conf and never overwrites your keys.
  • kittymux doctor explains every failure with the fix.
  • kittymux demo shows everything in an isolated window.
  • kittymux upgrade and kittymux hooks --remove give a clean path in and out.
  • Unit and shell suites, shellcheck -S error and a continuous integration workflow.
  • A fresh-home install, reinstall, validation and uninstall test.
  • Real-kitty rigs for states, clicks, drags, resize, the native divider, titles, join and the keymap overlay.
  • The README explains the states, privacy, keys, drag and drop, layout and upgrading.
  • The docs tree, with drift tests for links, chords and the CLI reference.
  • A first passing GitHub continuous integration run recorded on the release commit.
  • Screenshots or a recording for more than one theme. The demo ships one theme, and some images predate the status redesign.
  • A tagged release and changelog, with packaging/PKGBUILD checked against the tag.

Should

  • Verify screen markers against live Gemini, Cursor, OpenCode, Amp and Antigravity sessions.
  • Test on a second compositor, such as sway or niri, and on X11 with a real window manager.
  • Run tests/probe_panel.sh by hand on Hyprland, to move the docked panel from beta to shipped.
  • Decide the story for macOS, which needs a foreground-process read that does not use /proc.
  • Record a 60-second screen capture: the spinner, ! with its question, a ⊘ limit, and dragging a split into a tab.
  • Build the docs site. See Docs maintenance.

Before each release

Run the gates

Run the unit suite, the shell tests and every rig you can. Record each SKIP with its reason and the kitty version.

Check the docs

Run python3 -m unittest tests.test_docs and python3 tools/docs_status.py --check. Update docs/promotion-manifest.yaml dates for pages you reconciled.

Write the changelog line

Add a line under Unreleased in CHANGELOG.md for each user-visible change, then move them under the new version.

Apply it to your own kitties by reload only

Record window, tab and pane counts for every live kitty, run kittymux upgrade, and compare. Never restart a live kitty to apply a change.

Do not claim

  • "Works everywhere." See Platforms and compatibility.
  • "Zero overhead." The bar draw measured about 0.09 ms per tab, and the scan tick is 0.5 seconds. That is low, not zero.
  • "Zero background processes." There is no always-on daemon, but overlays, collectors and notifications use bounded workers and processes.
  • "All bugs fixed" or "guaranteed viral." Keep test evidence and honest compatibility limits instead.
  • Live-provider or compositor verification from a mocked response or a virtual-display run. Keep continuous integration results, release tags, live-provider checks and compositor checks separate from local test results.

A demo should use synthetic panes and private state. Redact project paths, prompts and account details.

Docs maintenance

How the docs are structured, written and checked, how the status table is generated, and how this folder becomes the published site.

Roadmap

What to work on next, in order: why each item matters, what blocks it and what done looks like. The docked panel on a real desktop comes first.

On this page

Must: a stranger can install it and it worksShouldBefore each releaseRun the gatesCheck the docsWrite the changelog lineApply it to your own kitties by reload onlyDo not claim