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` - Update classifiers (Alpha→Beta→Stable)
- [ ] `setup.py` - Update classifiers

### Documentation
- [ ] `README.md` - Update badges, install commands, and announcements
- [ ] `docs/INSTALL.md` - Update version references in curl commands
- [ ] `docs/UPDATE.md` - Add "What's New" section for new version
- [ ] `SECURITY.md` - Update supported versions table

### Website
- [ ] `web/src/app/layout.tsx` - Update `softwareVersion` in schema
- [ ] `web/src/app/page.tsx` - Update version badge (e.g., "v0.5.0 Beta")
- [ ] `web/package.json` - Update version field

### Testing & Verification
- [ ] Run `make test` - All tests pass
- [ ] Run `make lint` - No linting errors
- [ ] Run `make typecheck` - No type errors
- [ ] Run `make build` - Package builds successfully

### 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",

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: Update all curl commands to use the new tag:

curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta

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

Update all curl command examples with the new version tag.

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/jatinkrmalik/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/layout.tsx

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

"softwareVersion": "0.5.0-beta",

4.2 Update web/src/app/page.tsx

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

<span className="hidden sm:inline-block text-xs bg-gradient-to-r from-primary/20 to-green-500/20 text-primary border border-primary/30 px-2.5 py-1 rounded-full font-semibold shadow-sm shadow-primary/20">
  v0.5.0 Beta
</span>

Update the hero badge (around line 310):

<span className="text-sm font-medium text-primary">
  Beta Release — Try it now!
</span>

4.3 Update web/package.json

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

Step 5: Verify Everything Works

Run the full verification suite:

# Run tests
make test

# Run linting
make lint

# Run type checking
make typecheck

# Build package
make build

# Test install script (optional but recommended)
./install.sh --tag=v0.5.0-beta --dry-run 2>/dev/null || true

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/jatinkrmalik/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/jatinkrmalik/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

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.