Skip to content

VoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.

feat(release): add an interactive release helper

velixio9bcab0022e7d
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 49c39b48e..8aaa21fe2 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -160,6 +160,24 @@ the opt-in **Beta** channel (below). Previews between betas are builds from
`main` (the `electron-build.yml` artifacts or Docker `:latest`), never a side
branch. No Tauri build is maintained.
+## Release helper
+
+`uv run python scripts/release.py` runs a release from a clean, up-to-date
+`main`. It asks **stable or beta**, suggests the next version, asks **draft or
+publish**, prints the plan, and only proceeds when you type the tag name.
+
+- **Draft:** bumps the three version files in lockstep, runs `uv lock`, writes
+ the `CHANGELOG.md` section from `[Unreleased]` (a stable release renames it; a
+ beta copies it), runs the version guards, commits, pushes `main` and the tag.
+ The tag push builds a draft release; nothing is public.
+- **Publish:** the same, then dispatches `electron-release.yml` with
+ `publish=true`. If the Mac/Windows signing secrets are missing or unreadable it
+ stops unless you explicitly accept unsigned installers.
+- `--publish vX.Y.Z[-beta.N]` publishes an existing draft build later.
+- `--dry-run` prints the plan and changes nothing.
+
+It does not replace the post-release verification below; run it every time.
+
## Beta channel
Beta is a second release channel cut from `main`, for testers who opt in under
diff --git a/scripts/release.py b/scripts/release.py
new file mode 100644
index 000000000..bd04bc079
--- /dev/null
+++ b/scripts/release.py
@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Interactive release helper: Stable or Beta, draft or publish, then confirm.
+
+ uv run python scripts/release.py # ask everything
+ uv run python scripts/release.py --dry-run # show the plan, change nothing
+ uv run python scripts/release.py --publish TAG # publish an existing draft
+
+Runs from a clean, up-to-date `main`. Bumps the three version files in lockstep,
+refreshes uv.lock, writes the CHANGELOG section, runs the version guards,
+commits, pushes, tags, and either leaves the build as a draft (tag push) or
+dispatches `electron-release.yml` with `publish`. Nothing leaves the machine
+until you type the tag name to confirm. See docs/RELEASING.md.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from prepare_electron_release import channel_for # noqa: E402
+
+GUARD_TESTS = [
+ "tests/test_app_version.py",
+ "tests/test_voicestudio_branding.py",
+ "tests/test_changelog_style.py",
+]
+SIGNING_SECRETS = ("ELECTRON_MACOS_CSC_LINK", "ELECTRON_WINDOWS_CSC_LINK", "APPLE_ID")
+_VERSION = re.compile(r"(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?")
+
+
+def next_version(current: str, channel: str) -> str:
+ """Suggest the next version: beta -> beta.N+1 or next patch beta.1; stable -> final."""
+ match = _VERSION.fullmatch(current)
+ if not match:
+ raise ValueError(f"Not a stable or beta version: {current}")
+ major, minor, patch, beta = (int(g) if g else None for g in match.groups())
+ base = f"{major}.{minor}.{patch}"
+ if channel == "stable":
+ return base if beta is not None else f"{major}.{minor}.{patch + 1}"
+ if channel != "beta":
+ raise ValueError(f"Unknown channel: {channel}")
+ if beta is not None:
+ return f"{base}-beta.{beta + 1}"
+ return f"{major}.{minor}.{patch + 1}-beta.1"
+
+
+def bump_files(root: Path, version: str) -> None:
+ """Set the canonical version and its two toolchain mirrors."""
+ targets = [
+ ("package.json", r'(?m)^(\s*"version":\s*")[^"]+(")'),
+ ("pyproject.toml", r'(?m)^(version\s*=\s*")[^"]+(")'),
+ ("backend/core/version.py", r'(?m)^(_FALLBACK_VERSION\s*=\s*")[^"]+(")'),
+ ]
+ for name, pattern in targets:
+ path = root / name
+ text = path.read_text(encoding="utf-8")
+ updated, count = re.subn(pattern, rf"\g<1>{version}\g<2>", text, count=1)
+ if count != 1:
+ raise ValueError(f"Could not find the version in {name}")
+ path.write_text(updated, encoding="utf-8")
+
+
+def prepare_changelog(text: str, version: str, today: datetime.date) -> str:
+ """Return the changelog with a `## [version]` section; a no-op if one exists.
+
+ Stable renames `[Unreleased]` and starts a fresh one. Beta copies it, so the
+ next beta or the final stable release still carries the full list.
+ """
+ if re.search(rf"^## \[{re.escape(version)}\]", text, re.M):
+ return text
+ match = re.search(r"^## \[Unreleased\][^\n]*\n(.*?)(?=^## \[|\Z)", text, re.M | re.S)
+ if not match or not match.group(1).strip():
+ raise ValueError("CHANGELOG.md has no [Unreleased] entries to release")
+ body = match.group(1).strip("\n")
+ heading = f"## [{version}] — {today.isoformat()}"
+ if channel_for(version) == "stable":
+ section = f"## [Unreleased]\n\n{heading}\n\n{body}\n\n"
+ else:
+ section = f"## [Unreleased]\n\n{body}\n\n{heading}\n\n{body}\n\n"
+ return text[: match.start()] + section + text[match.end():]
+
+
+def sh(*cmd: str, check: bool = True, capture: bool = False) -> str:
+ result = subprocess.run(
+ cmd, cwd=ROOT, check=check, text=True, capture_output=capture, encoding="utf-8"
+ )
+ return (result.stdout or "").strip() if capture else ""
+
+
+def ask(question: str, choices: list[str], default: str | None = None) -> str:
+ hint = "/".join(c.upper() if c == default else c for c in choices)
+ while True:
+ answer = input(f"{question} [{hint}] ").strip().lower() or (default or "")
+ if answer in choices:
+ return answer
+ print(f" Please answer one of: {', '.join(choices)}")
+
+
+def preflight(tag: str | None = None) -> None:
+ problems = []
+ if sh("git", "branch", "--show-current", capture=True) != "main":
+ problems.append("not on main (releases are always cut from main)")
+ if sh("git", "status", "--porcelain", "--untracked-files=no", capture=True):
+ problems.append("tracked files have uncommitted changes")
+ sh("git", "fetch", "-q", "origin", "main")
+ if sh("git", "rev-parse", "HEAD", capture=True) != sh("git", "rev-parse", "origin/main", capture=True):
+ problems.append("main is not identical to origin/main (pull or push first)")
+ if subprocess.run(["gh", "auth", "status"], cwd=ROOT, capture_output=True).returncode:
+ problems.append("gh is not authenticated")
+ if tag and sh("git", "ls-remote", "--tags", "origin", tag, capture=True):
+ problems.append(f"tag {tag} already exists on origin")
+ if problems:
+ raise SystemExit("Cannot release:\n - " + "\n - ".join(problems))
+
+
+def missing_signing_secrets() -> list[str]:
+ result = subprocess.run(
+ ["gh", "secret", "list", "--json", "name", "--jq", ".[].name"],
+ cwd=ROOT, capture_output=True, text=True,
+ )
+ if result.returncode:
+ return list(SIGNING_SECRETS) # cannot tell; ask rather than assume signed
+ present = set(result.stdout.split())
+ return [name for name in SIGNING_SECRETS if name not in present]
+
+
+def dispatch_publish(tag: str, allow_unsigned: bool) -> None:
+ sh(
+ "gh", "workflow", "run", "electron-release.yml", "--ref", "main",
+ "-f", f"release_tag={tag}", "-f", "publish=true",
+ "-f", f"allow_unsigned={str(allow_unsigned).lower()}",
+ )
+
+
+def publish_existing(tag: str) -> None:
+ channel = channel_for(tag.removeprefix("v"))
+ preflight()
+ unsigned = False
+ if missing_signing_secrets():
+ unsigned = ask("Signing secrets missing or unreadable. Ship UNSIGNED installers?", ["y", "n"], "n") == "y"
+ print(f"\nPublish {tag} ({channel}) from its existing build{' (unsigned)' if unsigned else ''}.")
+ if input(f"Type {tag} to confirm: ").strip() != tag:
+ raise SystemExit("Cancelled.")
+ dispatch_publish(tag, unsigned)
+ print("Dispatched electron-release.yml with publish=true. Watch: gh run list --workflow electron-release.yml")
+
+
+def release(args: argparse.Namespace) -> None:
+ current = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["version"]
+ preflight()
+ channel = ask("Release channel?", ["stable", "beta"])
+ suggestion = next_version(current, channel)
+ version = input(f"Version [{suggestion}]: ").strip() or suggestion
+ if channel_for(version) != channel:
+ raise SystemExit(f"{version} is not a {channel} version")
+ tag = f"v{version}"
+ preflight(tag)
+ mode = ask("Draft (build only, publish later) or publish now?", ["draft", "publish"], "draft")
+ unsigned = False
+ if mode == "publish" and missing_signing_secrets():
+ print("Signing secrets are missing or unreadable (Mac/Windows signing).")
+ unsigned = ask("Ship UNSIGNED installers?", ["y", "n"], "n") == "y"
+ if not unsigned:
+ raise SystemExit("Cancelled: configure signing, or choose draft.")
+
+ print(f"""
+Release plan
+ channel {channel} ({'GitHub prerelease, never latest; :beta Docker' if channel == 'beta' else 'GitHub latest; :stable Docker'})
+ version {current} -> {version} tag {tag}
+ mode {mode}{' (UNSIGNED installers)' if unsigned else ''}
+ steps bump 3 version files + uv lock + CHANGELOG, run guards,
+ commit + push main, push tag{', then publish' if mode == 'publish' else ' (draft release; publish later with --publish)'}""")
+ if args.dry_run:
+ print("\n--dry-run: nothing changed.")
+ return
+ if input(f"\nThis pushes to main and tags. Type {tag} to confirm: ").strip() != tag:
+ raise SystemExit("Cancelled.")
+
+ bump_files(ROOT, version)
+ changelog = ROOT / "CHANGELOG.md"
+ changelog.write_text(
+ prepare_changelog(changelog.read_text(encoding="utf-8"), version, datetime.date.today()),
+ encoding="utf-8",
+ )
+ sh("uv", "lock")
+ sh("uv", "run", "pytest", *GUARD_TESTS, "-q")
+ sh("git", "add", "package.json", "pyproject.toml", "backend/core/version.py", "uv.lock", "CHANGELOG.md")
+ sh("git", "commit", "-m", f"chore(release): {tag}")
+ sh("git", "push", "origin", "main")
+ sh("git", "tag", tag)
+ sh("git", "push", "origin", tag)
+ if mode == "publish":
+ # The tag push starts a build-only run; the dispatch builds and publishes.
+ runs = sh("gh", "run", "list", "--workflow", "electron-release.yml", "--branch", tag,
+ "--event", "push", "--json", "databaseId", "--jq", ".[].databaseId", capture=True)
+ for run_id in runs.split():
+ sh("gh", "run", "cancel", run_id, check=False)
+ dispatch_publish(tag, unsigned)
+ print(f"\nPublishing {tag}. Then verify: docs/RELEASING.md → Beta channel / verification table.")
+ else:
+ print(f"\nDraft build started for {tag}. Publish later: uv run python scripts/release.py --publish {tag}")
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--dry-run", action="store_true", help="show the plan and change nothing")
+ parser.add_argument("--publish", metavar="TAG", help="publish an existing draft build of TAG")
+ args = parser.parse_args()
+ if args.publish:
+ publish_existing(args.publish)
+ else:
+ release(args)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_release_script.py b/tests/test_release_script.py
new file mode 100644
index 000000000..21ac26d89
--- /dev/null
+++ b/tests/test_release_script.py
@@ -0,0 +1,160 @@
+"""scripts/release.py: version suggestions, lockstep bump and changelog section."""
+from __future__ import annotations
+
+import datetime
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+TODAY = datetime.date(2026, 10, 23)
+
+
[email protected](scope="module")
+def release():
+ spec = importlib.util.spec_from_file_location("release_script", ROOT / "scripts/release.py")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+ ("current", "channel", "expected"),
+ [
+ ("0.5.7", "stable", "0.5.8"),
+ ("0.5.7", "beta", "0.5.8-beta.1"),
+ ("0.5.8-beta.1", "beta", "0.5.8-beta.2"),
+ ("0.5.8-beta.9", "beta", "0.5.8-beta.10"),
+ ("0.5.8-beta.2", "stable", "0.5.8"),
+ ],
+)
+def test_next_version(release, current, channel, expected):
+ assert release.next_version(current, channel) == expected
+
+
+def test_next_version_rejects_other_shapes(release):
+ with pytest.raises(ValueError):
+ release.next_version("0.5.8-rc.1", "beta")
+ with pytest.raises(ValueError):
+ release.next_version("0.5.8", "nightly")
+
+
+def test_bump_files_moves_all_three_and_only_the_version(release, tmp_path):
+ (tmp_path / "backend/core").mkdir(parents=True)
+ (tmp_path / "package.json").write_text(
+ '{\n "name": "x",\n "version": "0.5.7",\n "dependencies": {"v": "1.0.0"}\n}\n'
+ )
+ (tmp_path / "pyproject.toml").write_text(
+ '[project]\nname = "x"\nversion = "0.5.7"\n[tool]\nversion = "9"\n'
+ )
+ (tmp_path / "backend/core/version.py").write_text('_FALLBACK_VERSION = "0.5.7"\n')
+ release.bump_files(tmp_path, "0.5.8-beta.1")
+
+ assert json.loads((tmp_path / "package.json").read_text())["version"] == "0.5.8-beta.1"
+ assert 'version = "0.5.8-beta.1"' in (tmp_path / "pyproject.toml").read_text()
+ assert 'version = "9"' in (tmp_path / "pyproject.toml").read_text()
+ assert '_FALLBACK_VERSION = "0.5.8-beta.1"' in (tmp_path / "backend/core/version.py").read_text()
+
+
+def test_bump_files_fails_loudly_when_a_mirror_is_missing(release, tmp_path):
+ (tmp_path / "backend/core").mkdir(parents=True)
+ (tmp_path / "package.json").write_text('{\n "version": "0.5.7"\n}\n')
+ (tmp_path / "pyproject.toml").write_text("[project]\n")
+ (tmp_path / "backend/core/version.py").write_text("")
+ with pytest.raises(ValueError, match="pyproject.toml"):
+ release.bump_files(tmp_path, "0.5.8")
+
+
+CHANGELOG = "# Changelog\n\n## [Unreleased]\n\n**Highlights**\n\n- A (#1)\n\n## [0.5.7] — 2026-10-01\n\n- Old (#2)\n"
+
+
+def test_stable_renames_unreleased_and_starts_a_fresh_one(release):
+ text = release.prepare_changelog(CHANGELOG, "0.5.8", TODAY)
+ assert text.index("## [Unreleased]") < text.index("## [0.5.8] — 2026-10-23") < text.index("## [0.5.7]")
+ unreleased, rest = text.split("## [0.5.8]")
+ assert "- A (#1)" not in unreleased and "- A (#1)" in rest
+
+
+def test_beta_copies_unreleased_so_it_stays_for_the_final_release(release):
+ text = release.prepare_changelog(CHANGELOG, "0.5.8-beta.1", TODAY)
+ assert text.count("- A (#1)") == 2
+ assert text.index("## [Unreleased]") < text.index("## [0.5.8-beta.1] — 2026-10-23")
+
+
+def test_existing_section_is_left_alone_and_empty_unreleased_is_refused(release):
+ done = release.prepare_changelog(CHANGELOG, "0.5.7", TODAY)
+ assert done == CHANGELOG
+ with pytest.raises(ValueError, match="no \\[Unreleased\\] entries"):
+ release.prepare_changelog("## [Unreleased]\n\n## [0.5.7] — x\n\n- a\n", "0.5.8", TODAY)
+
+
[email protected]("version", ["0.5.8", "0.5.8-beta.3"])
+def test_generated_changelog_passes_the_release_notes_extraction(release, version):
+ """prepare_electron_release.py extracts `## [version]`; the section must be non-empty."""
+ import re
+
+ text = release.prepare_changelog(CHANGELOG, version, TODAY)
+ section = re.search(
+ rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## |\Z)", text, re.M | re.S
+ )
+ assert section and section[1].strip()
+
+
+def _drive(release, monkeypatch, answers, *, dry_run, secrets_missing=()):
+ """Run release() with scripted prompts and every side effect recorded, not run."""
+ import argparse
+
+ calls = []
+ feed = iter(answers)
+ monkeypatch.setattr("builtins.input", lambda prompt="": next(feed))
+ monkeypatch.setattr(release, "preflight", lambda tag=None: None)
+ monkeypatch.setattr(release, "missing_signing_secrets", lambda: list(secrets_missing))
+ monkeypatch.setattr(release, "sh", lambda *cmd, **kw: calls.append(cmd) or "")
+ monkeypatch.setattr(release, "bump_files", lambda *a: calls.append(("bump", *a[1:])))
+ monkeypatch.setattr(release, "dispatch_publish", lambda *a: calls.append(("dispatch", *a)))
+ monkeypatch.setattr(
+ release.Path, "write_text", lambda self, *a, **k: calls.append(("write", self.name))
+ )
+ monkeypatch.setattr(release, "prepare_changelog", lambda text, *a: text)
+ release.release(argparse.Namespace(dry_run=dry_run))
+ return calls
+
+
+def _current(release):
+ return json.loads((ROOT / "package.json").read_text())["version"]
+
+
+def test_dry_run_shows_the_plan_and_changes_nothing(release, monkeypatch, capsys):
+ calls = _drive(release, monkeypatch, ["beta", "", "draft"], dry_run=True)
+ assert calls == []
+ out = capsys.readouterr().out
+ assert "prerelease, never latest" in out and "nothing changed" in out
+
+
+def test_a_wrong_confirmation_cancels_before_any_change(release, monkeypatch):
+ with pytest.raises(SystemExit, match="Cancelled"):
+ _drive(release, monkeypatch, ["stable", "", "draft", "yes"], dry_run=False)
+
+
+def test_a_version_of_the_other_channel_is_refused(release, monkeypatch):
+ with pytest.raises(SystemExit, match="not a beta version"):
+ _drive(release, monkeypatch, ["beta", "9.9.9"], dry_run=True)
+
+
+def test_draft_pushes_the_tag_but_never_dispatches_a_publish(release, monkeypatch):
+ tag = f"v{release.next_version(_current(release), 'beta')}"
+ calls = _drive(release, monkeypatch, ["beta", "", "draft", tag], dry_run=False)
+ assert ("git", "push", "origin", tag) in calls
+ assert not any(c[0] == "dispatch" for c in calls)
+
+
+def test_publish_without_signing_is_refused_unless_unsigned_is_accepted(release, monkeypatch):
+ tag = f"v{release.next_version(_current(release), 'stable')}"
+ with pytest.raises(SystemExit, match="configure signing"):
+ _drive(release, monkeypatch, ["stable", "", "publish", "n"], dry_run=False,
+ secrets_missing=["APPLE_ID"])
+ calls = _drive(release, monkeypatch, ["stable", "", "publish", "y", tag], dry_run=False,
+ secrets_missing=["APPLE_ID"])
+ assert ("dispatch", tag, True) in calls