Releasing¶
Releases are cut by the maintainer. Pushing a v* tag runs the Release workflow, which resolves the wheel, builds the package, publishes it to PyPI and creates a GitHub Release. PyPI never accepts the same version twice, so a broken release needs a new tag, and a pushed tag cannot be undone. Never create or push a v* tag unless you are releasing.
Version numbers¶
The package version comes from the tag (hatch-vcs), so the tag must be a valid PEP 440 version:
- Final releases:
vX.Y.Z, for examplev0.13.0. - Betas:
vX.Y.ZbN, for examplev0.13.0b1, thenb2,b3and so on before the finalvX.Y.Z. UseaNandrcNthe same way for alphas and release candidates.
Pre-release tags are published as GitHub pre-releases, and uv installs them only when asked: uv tool install --prerelease-package z-vision-generator=allow z-vision-generator, or an exact pin such as uv tool install z-vision-generator==0.13.0b1.
Final release tags also run the Deploy Docs workflow, which publishes the docs site from the tagged commit. Pre-release tags leave the published docs unchanged; run the Deploy Docs workflow by hand to publish between releases. A manual run publishes main, so the docs of every feature not yet released go live with it.
Checklist¶
Do these in order, on the commit you will tag.
- Land everything. The branch to release is on the newest
main, andmake checkpasses. - Check the curated LoRA list. Run
make check-curated. It asks the Hub for every entry at its pinned commit, with no token, and compares each file's size andlfs.sha256with the list. It exits with an error and names each entry whose file is missing, changed or unreachable; fix or drop those entries first. The same run rewrites each entry'sdownloadswith the repository's current Hugging Face download count incurated_loras.json, so commit the file afterwards (--no-writechecks without writing). It needs the network, so it is not part ofmake check. See The curated LoRA list. - Check that the wheel resolves.
scripts/check_wheel_resolves.shbuilds the wheel and resolves it from an empty directory withuv pip compile --no-configfor three fixed targets, from any host: Linux (x86_64-unknown-linux-gnu, PyPI only), Windows (x86_64-pc-windows-msvc, with--torch-backend cu132, as on the install page) and macOS (aarch64-apple-darwinwithMACOSX_DEPLOYMENT_TARGET=14.0, because uv assumes macOS 13 for that target whilemlxships only macOS 14 and newer wheels). A user installs the wheel withuv tool install z-vision-generator, where nothing of the repository'suv.lockor[tool.uv]settings applies; the script fails when a dependency has no solution next to ours, or whengradio,qwen-tts-hforfaster-qwen3-ttscomes back. CI runs it on every pull request, on its macOS runner, and the Release workflow runs it on an Ubuntu runner before it publishes; the script resolves all three targets from either host. - Write the release commit. Move the
[Unreleased]entries ofCHANGELOG.mdunder a## [<version>] - <date>heading, in a commit namedchore(release): v<version>whose body lists the release highlights. For a final release, the Release workflow uses that section as the GitHub release's description and stops before publishing if it is missing; pre-releases get none. - Check the install guide's launcher links. If Install links a
launcher-v*release, that release must exist before you tag, because the docs deploy on every final app tag and would otherwise publish dead download links. - Tag and push. Create the tag on that commit and push the commit and the tag. The Release workflow takes it from there.
- Check the result. The workflow's run is green, the version is on PyPI, the GitHub Release exists, and for a final release the docs site shows the new version.
Launcher releases¶
The desktop launcher is released apart from the app. It has its own version, in launcher/src-tauri/Cargo.toml, and its own workflow, started by launcher-v* tags. A v* tag never builds it, and a launcher-v* tag never publishes to PyPI. The app's version reads only v* tags, so launcher-v* tags never affect it. Which app version it installs comes from PyPI, so an app release needs no launcher release, except when the app needs something the launcher doesn't provide, such as a newer Python.
The launcher hard-codes things the app owns: the Python version, the Windows --torch-backend cu132 and the uv version. When the app changes any of these, ship a launcher release first, because older launchers' Update will fail or change nothing. See Desktop launcher for how it is built.
The release is not marked latest, so app releases stay on top; that is why the install guide links to the exact launcher-v… release and the asset names stay fixed. A pushed launcher-v* tag cannot be undone.
Do these in order.
- Land everything. The branch is on the newest
main, andmake launcher-testandmake checkpass. - Bump the version. Set
versioninlauncher/src-tauri/Cargo.toml. The workflow fails a tag whose version differs from it. - Update the pins if a tool has moved or a download has gone, as in Pins.
- Run a test build. Start the Launcher release workflow by hand from the branch. It builds the installers for macOS, Windows and Linux and uploads them as artifacts, and publishes nothing.
- Check each platform with the installers from the test build: a fresh install, start, Quit, Update, Repair and Uninstall, and the first-open steps on the install page. Include a Windows account whose name has spaces or non-ASCII characters, the tray on stock GNOME and the AppImage on a fresh Ubuntu. These need a real machine:
- Windows: turn on Start at login, then sign out and in. The launcher starts hidden and opens no browser.
- Windows: Quit, Update and Uninstall with other apps open. Only the launcher's own processes stop.
- macOS: the first install on a Mac without the Command Line Tools shows no "install developer tools" popup.
- macOS: open the launcher from the disk image. The window says to quit and move it; after the move, the copy in Applications opens.
- macOS: log out with Reopen windows when logging back in ticked. The launcher does not reopen its window.
- macOS: after Open Anyway, install and start both work, so Gatekeeper does not kill the managed Python.
- Update the install guide. Point the download links in Install at the new
launcher-v<version>release. - Tag and push. Create
launcher-v<version>on the commit and push the commit and the tag. The workflow builds the installers again and creates the GitHub release with the five files. - Deploy the docs once the release exists, so that the install page's links work: run the Deploy Docs workflow by hand, since a
launcher-v*tag does not run it. - Check the result. The release is not marked latest, each of the five files downloads, and the install page links to them.