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 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)

Quick Release Checklist

Use this checklist for every release:

## 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 release announcement and status references
- [ ] `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
- [ ] 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 `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`

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

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

2.2 Update pyproject.toml

Change the Development Status classifier:

# 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 PKGBUILD: bump pkgver / _tag; leave sha256sums=('SKIP') until the tag tarball exists. The release workflow runs updpkgsums when publishing to the AUR.
• 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 status (honest)
9. 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

Status Badge (line ~6):

<!-- Alpha -->
[![Status: Alpha](https://img.shields.io/badge/Status-Alpha-orange)]

<!-- Beta -->
[![Status: Beta](https://img.shields.io/badge/Status-Beta-blue)]

<!-- Stable -->
[![Status: Stable](https://img.shields.io/badge/Status-Stable-brightgreen)]

Install Commands: Keep install commands on main/install.sh (installer resolves latest release tag automatically):

curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh | bash

Release Announcement (lines ~31-34):

> 🎉 **Beta Release!**
>
> We're excited to share Vocalinux Beta with the community.
> This release is feature-complete and ready for broader testing.

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:

## 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:

| 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):

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

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

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

{
  "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:

# 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

# 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:

# 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)
2. Create a GitHub Release with auto-generated notes
3. Publish to PyPI
4. Deploy the website to vocalinux.com
5. 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 PyPI package was published (if applicable)
• Verify website was deployed (check vocalinux.com)
• Announce on social media/communities
• Update any pinned issues or discussions

Emergency Hotfix Process

For critical bugs in a released version:

# 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

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.