voculinux/docs/RELEASE_PROCESS.md

# Vocalinux Release Process

This document outlines the step-by-step process for creating a new release of Vocalinux.

## Overview

Vocalinux uses [Semantic Versioning](https://semver.org/) with pre-release suffixes:
- **Alpha**: Early testing phase (e.g., `0.4.1-alpha`)
- **Beta**: Feature-complete, testing phase (e.g., `0.5.0-beta`)
- **RC** (Release Candidate): Final testing before stable (e.g., `0.5.0-rc1`)
- **Stable**: Production-ready (e.g., `1.0.0`)

## Release Infrastructure (one-time setup)

These are configured once per repository. A tag pushed before they exist will fail
in the corresponding job.

### PyPI trusted publishing (required)

`publish-pypi` authenticates with a short-lived OIDC token instead of a stored API
token, so there is no `PYPI_API_TOKEN` secret to leak or rotate. It only works once
PyPI knows about this workflow. On https://pypi.org/manage/project/vocalinux/settings/publishing/
add a GitHub publisher:

| field | value |
|---|---|
| Owner | `VocaHQ` |
| Repository | `vocalinux` |
| Workflow name | `release.yml` |
| Environment | `pypi` |

Until that publisher exists, `publish-pypi` fails with `invalid-publisher`. The old
`PYPI_API_TOKEN` secret can be deleted from the repository once the first trusted
publish succeeds.

### AUR (optional)

`publish-aur` skips itself when `AUR_SSH_PRIVATE_KEY` is unset. See docs/AUR.md.

## Quick Release Checklist

Use this checklist for every release:

```markdown
## Version Bump Checklist for X.Y.Z-PHASE

### Core Version Files
- [ ] `src/vocalinux/version.py` - Update `__version__` and `__version_info__`
- [ ] `pyproject.toml` - Confirm `Development Status` classifier and `requires-python` are correct for this release phase

### Documentation
- [ ] `README.md` - Update short current-release blurb (not full notes)
- [ ] `CHANGELOG.md` - Point "Current stable" at the new tag
- [ ] `docs/INSTALL.md` - Verify install examples use `main/install.sh` (not version-pinned raw URLs)
- [ ] `docs/UPDATE.md` - Add "What's New" section for new version
- [ ] `SECURITY.md` - Update supported versions table

### Website
- [ ] `web/src/app/page.tsx` - Update `softwareVersion` in schema
- [ ] `web/src/app/page.tsx` - Update version badge / live version surfaces if present
- [ ] `web/src/app/changelog/page.tsx` - Add new release entry to changelog
- [ ] `web/package.json` - Update version field
- [ ] `web/package-lock.json` - Keep top-level/version metadata aligned with `web/package.json`
- [ ] `web/PRODUCT.md` - Keep capabilities aligned with shipped features
- [ ] Confirm install docs/website mention **AppImage** when this release ships AppImages

### Testing & Verification
Install `just` from https://just.systems or the distro package `just`.
- [ ] Run `just test` - All tests pass
- [ ] Run `just lint` - No linting errors
- [ ] Run `just typecheck` - No type errors
- [ ] Run `just build` - Package builds successfully
- [ ] Run `PYTHON=python3.11 just reproducible-wheel` - Independent wheels match
- [ ] Run `npm run build` in `web/` - Website builds successfully

> Note: CI workflows also sync website version metadata from `src/vocalinux/version.py`, but source files should still be updated in-repo during release prep for review clarity.

### Git Operations
- [ ] Create release branch: `git checkout -b release/vX.Y.Z-PHASE`
- [ ] Commit all version changes
- [ ] Push branch and create PR
- [ ] After PR merge, create tag: `git tag -a vX.Y.Z-PHASE -m "Release X.Y.Z-PHASE"`
- [ ] Push tag: `git push origin vX.Y.Z-PHASE`

### After the release run finishes
- [ ] Run `just verify-release` - the published release verifies as published
- [ ] Re-run it after any hand edit to the release: attaching an asset, or rewriting the notes
```

`verify-release.yml` runs the same check when the release workflow finishes.
It cannot see a hand edit made afterwards, which is how every v0.16.2 defect
arrived, so run it yourself after touching a published release. The one
exception is `snap-backfill.yml`: that workflow attaches the snap, rewrites
`SHA256SUMS`, and then runs `scripts/verify_release.py` itself.

### Pre-publication wheel reproducibility

PR CI and the release workflow run `scripts/build_reproducible_wheel.py` before
publication. It checks lock/export drift, installs the hash-pinned `release-build`
toolchain into two fresh virtualenvs without system site-packages, and independently
builds an sdist and its wheel in each source tree with `--no-isolation`.
`SOURCE_DATE_EPOCH` comes from
the checked-out commit. Both builds use the same Python 3.11 interpreter and
platform; this checks repeatability under controlled inputs, not cross-platform
or cross-Python-version reproducibility. Only wheels are compared byte-for-byte.

Build-only environments deliberately exclude host packages and setuptools plugins.
Unlike runtime/development virtualenvs, they do not need distro PyGObject: the
backend reads version metadata without importing GTK.

The script runs `twine check --strict` with the locked tools and stages only the
canonical wheel and sdist in `dist/` after comparison succeeds. All release
consumers reuse those distributions. Snap Store publication also waits for this
gate. Verification builds never enter the release checksum manifest.

Locally, `PYTHON=python3.11 just reproducible-wheel` includes tracked working-tree
edits and non-ignored new files, but excludes ignored build/egg-info/venv state.
Repeat runs automatically clean the gate's previous logs and build archives.
Staged files in `dist/` are removed only if their names and digests match the
retained canonical archives. Unrelated or modified files, unexpected diagnostic
files, and symlinks cause cleanup to stop before deleting anything; move those
files aside first. The rest of `build/` is never cleaned. Logs, hashes and both
builds are retained in `build/reproducible-wheel/`; CI uploads that directory on failure.
Refresh the toolchain through `just lock`, not by editing its export by hand.
Cleanup removes staged copies before their canonical originals, so an interrupted
cleanup can safely be retried.
The gate holds a checkout lock from before cleanup through final staging; a second
active run fails without changing the first run's outputs. Archives are copied to
an ignored temporary sibling of `dist/` and then atomically renamed into place,
so interrupted staging leaves only complete archives in `dist/` and can be retried.

### AUR source publication gate

After `publish-checksums`, `aur-source-test` downloads the published canonical
sdist and `SHA256SUMS`. `scripts/prepare_aur_source.py` checks the digest and
cryptographically verifies provenance against this repository's release workflow,
tag ref and source commit before preparing the checksum-pinned PKGBUILD.
The exact prepared recipe is built, checked with namcap, installed and smoked on
current Arch. `publish-aur` downloads only that verified PKGBUILD artifact and
pushes it without further version/checksum rewrites (`updpkgsums: false`).

This gate runs even without AUR publication credentials. Failure prevents the
AUR push, but does not unpublish GitHub/PyPI artifacts already released. It is
separate from PR/local `--local-unattested` fixtures, which exercise the same
preparation/build path but are never used for publication. See [AUR.md](AUR.md)
for the trust model and the existing AUR-provider smoke-test limitations.
`vocalinux-bin` publication waits only for release creation and both AppImages;
source-gate failures or unrelated checksum producers do not block it.

## Detailed Release Steps

### Step 1: Determine Version Number

Follow semantic versioning:

```
Given version MAJOR.MINOR.PATCH-PHASE:

MAJOR - Breaking changes (for 1.0.0: public API stable)
MINOR - New features, backwards compatible
PATCH - Bug fixes, backwards compatible
PHASE - alpha, beta, rc1, rc2, etc. (omit for stable releases)
```

**Examples:**
- Alpha → Beta: `0.4.1-alpha` → `0.5.0-beta` (new features, phase change)
- Beta → RC: `0.5.0-beta` → `0.5.0-rc1` (same features, testing phase)
- RC → Stable: `0.5.0-rc1` → `1.0.0` (first stable release)
- Stable patch: `1.0.0` → `1.0.1` (bug fixes only)
- Stable minor: `1.0.0` → `1.1.0` (new features)

### Step 2: Update Core Version Files

#### 2.1 Update `src/vocalinux/version.py`

```python
__version__ = "0.5.0-beta"
__version_info__ = (0, 5, 0, "beta")
```

#### 2.2 Update `pyproject.toml`

Change the Development Status classifier:

```toml
# For Alpha:
"Development Status :: 3 - Alpha",

# For Beta:
"Development Status :: 4 - Beta",

# For Stable:
"Development Status :: 5 - Production/Stable",
```

### Patch releases within a minor line (e.g. 0.14.x)

When shipping bug fixes only (PATCH bump, same MINOR):

- **README / `docs/UPDATE.md` "What's New"** keeps the **minor-series feature list** (everything introduced in that 0.Y line) and adds a short **Bug fixes in this patch** subsection for the delta only. Do not make the marketing highlight table look featureless because this tag only contains fixes.
- **Website changelog** (`web/src/app/changelog/page.tsx`) may list only the delta for the new entry; older entries stay historical.
- **AppStream** (`packaging/flatpak/com.vocalinux.Vocalinux.metainfo.xml`): add a short `<release>` note for the patch delta only; leave the long product feature `<ul>` as series/product-level.
- **SECURITY.md** supported versions table usually stays on the minor line (`0.14.x`) without a row per patch.
- **AUR source PKGBUILD**: the release gate prepares `pkgver`, `_tag`, the normalized `_version`, and the canonical sdist digest, then tests that exact file. Do not introduce `SKIP` or rehash it during publication. The separate `vocalinux-bin` path still pins both AppImage digests before its own publication.
- **Dates**: patch release dates must not predate the previous release in changelog / AppStream / version history.

### GitHub Release Notes Writing Rules

Use these rules for every GitHub Release body (and for the draft pasted into the release-prep PR). Website changelog entries stay shorter; see below.

#### Sources of truth

- Delta commits: `git log vPREV..HEAD` plus merged PR titles/bodies.
- Closed issues via PR `Fixes` / `Closes` references only - do not invent issue numbers.
- Do not invent benchmarks, user counts, testimonials, or features not in the tree.

#### Required structure

1. `# Vocalinux vX.Y.Z` title
2. One to three plain sentences: what this release is for (no hype)
3. `## Highlights` - markdown table, about 4-8 rows
4. `## New Features` - bullets with PR + author; include issue closes when real
5. `## Bug Fixes` - group by area (IBus, Installer, AUR, Text injection, …)
6. Optional: `## Improvements`, `## Docs`, `## Packaging`
7. `## Thanks` - external PR authors and issue reporters by `@handle`
8. `## Install / Upgrade` - `install.sh`, AUR, PyPI, **AppImage**, Flatpak, Snap,
   `.deb` / `.rpm`
   (Store channels plus GitHub `.snap` sideload when Store review is pending)
9. `### Verifying what you downloaded` (required, and easy to lose). `release.yml`
   generates it, with `sha256sum -c --ignore-missing SHA256SUMS` and
   `gh attestation verify`. A hand-written body replaces the generated one, so carry
   this block over deliberately. v0.16.2 published a checksum manifest and build
   provenance and mentioned neither, so nothing a user reads told them either existed
10. Footer compare link: `https://github.com/VocaHQ/vocalinux/compare/vPREV...vX.Y.Z`

#### Include / exclude

- **Include:** user-visible features, install/packaging changes, desktop reliability fixes, docs that change user instructions.
- **Exclude or demote:** Dependabot-only bumps, CI matrix tweaks, agent-env docs, pure refactors - short “CI / maintenance” subsection at most.

#### Attribution and voice

- Feature/fix bullets: `(#N by @author; fixes #M reported by @reporter)` when known.
- Practical, specific, Linux-native. Name the symptom users hit.
- Avoid promotional filler (“seamless”, “pivotal”, “game-changer”, fake significance).

#### Website changelog vs GitHub Release

- **Website** (`web/src/app/changelog/page.tsx`): 3-10 concise user-facing bullets for the new entry.
- **GitHub Release**: fuller narrative + install block + thanks. Draft in the release-prep **PR body**; paste/edit onto the release after the tag workflow runs (workflow install stub + generated notes are a starting point only).

#### Minor vs patch (reminder)

- **Minor** (e.g. `0.15.0`): rewrite README / UPDATE “What’s New” for the new series; full website changelog entry; AppStream release note summarizes the series.
- **Patch** (e.g. `0.15.1`): keep series feature table; add “Bug fixes in this patch” only; website changelog lists delta only.

#### Draft delivery

- Release-prep PRs should include a `## Draft GitHub Release Notes` section in the PR description for review before tag.
- Do not tag from the prep branch alone; tag after merge to `main`.

### Step 3: Update Documentation

#### 3.1 Update `README.md`

**README current-release blurb:**
Keep a short one-line pointer to the new tag and [docs/UPDATE.md](UPDATE.md). Do not paste the full release notes into the README.

**Install commands:**
Keep install examples on `main/install.sh` (download-then-run preferred; installer resolves latest release tag):
```bash
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
bash /tmp/vl.sh
```

#### 3.2 Update `docs/INSTALL.md`

Confirm install examples point to `main/install.sh` and not release-tag raw URLs.

#### 3.3 Update `docs/UPDATE.md`

Add a new "What's New" section at the top:

```markdown
## What's New in v0.5.0-beta

- Feature 1
- Feature 2
- Bug fix 1

See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.5.0-beta).

---

## Previous Versions

### v0.4.1-alpha
...
```

#### 3.4 Update `SECURITY.md`

Update the supported versions table:

```markdown
| Version | Supported          |
| ------- | ------------------ |
| 0.5.x   | :white_check_mark: |
| 0.4.x   | :x:                |
| < 0.4   | :x:                |
```

### Step 4: Update Website

#### 4.1 Update `web/src/app/page.tsx`

Update the schema.org softwareVersion (around line 68):

```typescript
"softwareVersion": "vX.Y.Z-PHASE",
```

Update the version badge in the header (around line 293):

```tsx
vX.Y.Z Beta
```

#### 4.2 Update `web/src/app/changelog/page.tsx`

Add new release entry to the `releases` array at the top of the file.

#### 4.3 Update `web/package.json`

```json
{
  "name": "vocalinux-website",
  "version": "0.5.0"
}
```

Also align `web/package-lock.json` top-level `version` fields with `web/package.json`.

### Step 5: Verify Everything Works

Run the full verification suite. Install `just` from
https://just.systems or the distro package `just`.

```bash
# Run tests
just test

# Run linting
just lint

# Run type checking
just typecheck

# Build package
just build

# Website build
cd web && npm run build && cd ..

# Install script sanity checks (optional but recommended)
bash -n install.sh
./install.sh --help | grep -- --tag
```

### Step 6: Create Release Branch and PR

```bash
# Create branch
git checkout -b release/v0.5.0-beta

# Stage all changes
git add -A

# Commit with conventional commit format
git commit -m "chore(release): prepare v0.5.0-beta

- Update version from 0.4.1-alpha to 0.5.0-beta
- Update status badges from Alpha to Beta
- Update documentation version references
- Update website schema and badges
- Update pyproject.toml classifiers
- Update SECURITY.md supported versions table"

# Push branch
git push origin release/v0.5.0-beta

# Create PR (use GitHub CLI or web interface)
gh pr create --title "chore(release): prepare v0.5.0-beta" \
  --body "This PR prepares the repository for the v0.5.0-beta release.

## Changes
- Bumped version to 0.5.0-beta
- Updated status badges from Alpha to Beta
- Updated all documentation version references
- Updated website version info
- Updated SECURITY.md supported versions

## Checklist
- [x] All tests passing
- [x] Linting clean
- [x] Type checking clean
- [x] Package builds successfully"
```

### Step 7: Create and Push Tag (After PR Merge)

Once the PR is merged to main:

```bash
# Checkout main
git checkout main
git pull origin main

# Create annotated tag
git tag -a v0.5.0-beta -m "Vocalinux Beta Release 0.5.0

Key changes since 0.4.1-alpha:
- Feature 1
- Feature 2
- Bug fix 1

Full changelog: https://github.com/VocaHQ/vocalinux/releases"

# Push tag
git push origin v0.5.0-beta
```

### Step 8: Monitor Release

After pushing the tag, the GitHub Actions workflow will automatically:

1. Build the Python package (wheel and sdist) - **once**, with `SOURCE_DATE_EPOCH`
   pinned to the tagged commit. Every later job downloads that artifact instead of
   rebuilding, so the wheel on PyPI is byte-for-byte the wheel on the release
2. Build and attach AppImages for x86_64 and aarch64, both from that same wheel
3. Create a GitHub Release with auto-generated notes
4. Attach `SHA256SUMS` covering every GitHub asset (wheel, sdist, both AppImages,
   both Flatpaks, the amd64 snap, the `.deb` and `.rpm` for both arches) and
   generate build provenance from that
   manifest (runs after the aarch64 AppImage, both Flatpaks, and the snap land,
   so a partial manifest never gets published)
5. Publish to PyPI via trusted publishing
6. Publish the AUR package (when the `AUR_SSH_PRIVATE_KEY` secret is configured)
7. Publish the signed self-hosted Flatpak remote to `VocaHQ/vocalinux-flatpak`
   (stable tags only, once the GitHub Release exists, when
   `FLATPAK_GPG_PRIVATE_KEY` + `FLATPAK_REPO_TOKEN` are configured — see
   docs/FLATPAK_REMOTE.md)
8. Deploy the website to vocalinux.com
9. Build the amd64 snap, attach it to the GitHub Release, and try Snap Store
   `edge`/`candidate`. Store human review (for example a super-privileged
   `allow-installation` plug) must not block the GitHub `.snap`. `stable` does not auto-release (#783):
   after candidate QA, dispatch `snap-promote.yml`, which releases the
   candidate revision to `latest/stable`
10. Mark as pre-release if version contains alpha/beta/rc

Monitor at: https://github.com/VocaHQ/vocalinux/actions

### Step 9: Post-Release Tasks

- [ ] Verify GitHub Release was created correctly
- [ ] Verify `SHA256SUMS` is attached and lists every GitHub asset (wheel, sdist,
      both AppImages, both Flatpaks, the amd64 snap, the `.deb` and `.rpm` for
      both arches) - the release notes tell users to run `sha256sum -c`
      against it
- [ ] If the Store holds the snap for human review, confirm the GitHub `.snap`
      is still attached and the notes document `snap install --dangerous`
- [ ] After candidate QA (install, tray, mic, model download, typing into a real
      app), promote the snap to stable:
      `gh workflow run snap-promote.yml -f tag=vX.Y.Z` - it fails unless
      `latest/candidate` carries a revision whose version matches the tag. An
      optional `snap-stable` environment with required reviewers adds a second
      approval gate on the dispatch
- [ ] Verify provenance: `gh attestation verify <artifact> --repo VocaHQ/vocalinux`
- [ ] Verify PyPI package was published (if applicable), and that its wheel sha256
      matches the line for that wheel in `SHA256SUMS`
- [ ] Verify website was deployed (check vocalinux.com)
- [ ] If the Flatpak remote is configured, verify it picked up the tag:
      `flatpak remote-info vocahq com.vocalinux.Vocalinux` (docs/FLATPAK_REMOTE.md)
- [ ] Announce on social media/communities
- [ ] Update any pinned issues or discussions

## Emergency Hotfix Process

For critical bugs in a released version:

```bash
# Create hotfix branch from the tag
git checkout -b hotfix/v0.5.1-beta v0.5.0-beta

# Make fix, commit, push
git add -A
git commit -m "fix: critical bug description"
git push origin hotfix/v0.5.1-beta

# Create PR targeting main
# After merge, tag new version
git tag -a v0.5.1-beta -m "Hotfix release v0.5.1-beta"
git push origin v0.5.1-beta
```

## Version History

| Version | Date | Phase | Notes |
|---------|------|-------|-------|
| 0.2.0-alpha | 2024 | Alpha | Initial alpha |
| 0.3.0-alpha | 2024 | Alpha | - |
| 0.4.0-alpha | 2024 | Alpha | Multi-language support |
| 0.4.1-alpha | 2024 | Alpha | Language selector UI |
| 0.5.0-beta | 2025 | Beta | First beta release |
| 0.6.0-beta | 2026-02-11 | Beta | Web SEO, mobile responsiveness, improved Fedora support |
| 0.6.1-beta | 2026-02-12 | Beta | Device handling improvements |
| 0.6.2-beta | 2026-02-17 | Beta | Bug fixes |
| 0.6.3-beta | 2026-02-19 | Beta | GPU detection improvements |
| 0.7.0-beta | 2026 | Beta | Autostart, tabbed settings, Intel GPU support, single instance |
| 0.8.0-beta | 2026-03-01 | Beta | Push-to-talk mode, optional voice commands, input/audio compatibility fixes |
| 0.9.0-beta | 2026-03-14 | Beta | Left/right modifier keys, sound effects toggle, Wayland clipboard fallback, leading-space fix |
| 0.10.0-beta | 2026-03-25 | Beta | Keyboard/audio reliability hardening, IBus/tray stability fixes, CI + test coverage improvements |
| 0.10.1-beta | 2026-03-27 | Beta | Stability patch: tray resource bundling, engine-switch segfault prevention, settings close action, XKB layout preservation |
| 0.10.2-beta | 2026-04-08 | Beta | Non-ASCII text injection, IBus Wayland detection, Pop!_OS deps, code quality refactor |
| 0.11.0-beta | 2026-05-30 | Beta | Advanced Settings tab, IBus/recognition hardening, installer fixes, distro compatibility |
| 0.12.0-beta | 2026-06-07 | Beta | Remote API engine, Silero VAD, threading/IBus hardening, settings and installer fixes |
| 0.13.0-beta | 2026-06-30 | Beta | Guided whisper.cpp model variants, Wayland text-injection reliability, hotplug keyboard support, dictation spacing fix, website docs refresh |
| 0.14.0-beta | 2026-07-13 | Beta | Configurable modifier+key hotkeys, FunASR/SenseVoice remote-API support, GNOME/KDE Wayland IBus reliability fixes, audio crash fix, hybrid-CPU efficiency fix |
| 0.14.1 | 2026-07-17 | Stable | Flatpak packaging, AUR package, layout-aware hotkeys, installer/text-injection fixes |
| 0.14.2 | 2026-07-17 | Stable | IBus engine launch + FocusIn gate; settings tabs scroll to fit monitor |
| 0.15.0 | 2026-07-28 | Stable | Searchable settings + sidebar dictation footer, AppImage, expanded languages, dictation polish, auto-pause/keepalive, Vulkan device selection, ibus-wayland, Bluetooth mic + shortcut UI fixes |
| 0.16.0 | 2026-08-23 | Stable | Update checker + tray notify, Right Alt PTT default (new installs), searchable language list, delete unused models, Voca tone picker (family preview WAVs), About page, AGPL-3.0, family mic icons, installer/just/uv pinning, Test Dictation missing-model message, IBus/audio/clipboard/GPU/AppImage reliability, vocalinux.com family workbench restyle |
| 0.17.0 | 2026-09-16 | Stable | Faster Whisper + Parakeet engines, Speech Model simple setup, first-run system language, Snap with ydotool/uinput, Flatpak bundles on the GitHub Release, XWayland/layout paste and settings/audio fixes |
| 0.18.0 | 2026-10-02 | Stable | Dictation Pad, evdev hotkey suppression, PipeWire capture + system audio, RemoteDesktop portal injection, per-language shortcuts + tray history, TinyDiarize file transcription, D-Bus activation, custom dictionary, postprocessing hook, floating overlay, audio ducking, AUR -bin + self-hosted Flatpak remote + snap-promote |
| 0.18.1 | 2026-10-08 | Stable | Settings Proxy page, opt-in JSONL transcript persistence, .deb/.rpm release packages, slimmer tray menu, dictation-pad Wayland ghost fix, evdev keyboard-discovery tightening, KWin 6 case fix, staged model picker |
| 0.16.2 | 2026-09-05 | Stable | Patch: KDE leftover IBus skip, Wayland/IBus shortcuts via wtype/ydotool, BackSpace delete that, installer glslc on Fedora/Arch, nightly version stamp, release integrity pins, AUR PKGBUILD CI gate, distro CI/docs drift, Gateway Beta on site |
| 0.16.1 | 2026-08-30 | Stable | Patch: per-engine model at startup, leftover tray idle, terminal Ctrl+Shift+V paste, GNOME XWayland layout after IBus, Python 3.11 floor + verified downloads, AppImage glibc that boots on Debian 12, Settings/About polish |

## Questions?

If you're unsure about any step:
1. Check previous releases for examples
2. Review the GitHub Actions workflows in `.github/workflows/`
3. Ask in the project's discussions

---

**Note**: This document should be updated when the release process changes.