Release Process

MIRA follows Semantic Versioning and a phased release model: Beta → Release Candidate → Stable. Releases are driven by release-it with auto-generated changelogs from Conventional Commits.

Release phases

Phase	Version format	Purpose
Beta	`0.1.0-beta.1`, `0.1.0-beta.2`, …	Public beta — gathering real-world feedback
Release Candidate	`1.0.0-rc.1`, `1.0.0-rc.2`, …	Feature-frozen, critical fixes only
Stable GA	`1.0.0`	Announced broadly — the production release
Patch	`1.0.1`, `1.0.2`, …	Bug fixes after GA
Minor	`1.1.0`, `1.2.0`, …	New features after GA
Major	`2.0.0`, …	Breaking changes to IPC, DB schema, or engine API

Version bump rules (after GA)

Change type	Version bump	Example
Breaking change to IPC, DB schema, or engine API	MAJOR	`1.0.0 → 2.0.0`
New feature or significant improvement	MINOR	`1.0.0 → 1.1.0`
Bug fix or documentation update	PATCH	`1.0.0 → 1.0.1`

Step 1 — Write conventional commits

Every commit that will appear in the changelog must follow the Conventional Commits format:

<type>(<scope>): <short description>

[optional body]
[optional footer]

Types and their changelog impact:

Type	Changelog section	Version bump
`feat:`	✨ Features	MINOR
`fix:`	🐛 Bug Fixes	PATCH
`perf:`	⚡ Performance	PATCH
`docs:`	📚 Documentation	none
`BREAKING CHANGE:`	💥 Breaking Changes	MAJOR
`chore:`, `ci:`, `test:`, `refactor:`	(skipped)	none

Examples:

git commit -m "feat(repl): add colour-coded stderr stream"
git commit -m "fix(nae): handle token budget overflow gracefully"
git commit -m "feat!: redesign IPC session contract"   # ! = breaking change

A commit-msg git hook (via husky + commitlint) rejects commits that don’t follow this format. This is enforced automatically after npm install.

Step 2 — Cut a release

All releases are cut from the mira-app/ directory using release-it. The tool:

Bumps the version in package.json
Generates a CHANGELOG.md entry from commits since the last tag
Creates a git commit + tag
Pushes to main
Creates a GitHub Release with the installer artifacts attached

Beta release

cd mira-app
npm run release:beta
# Cuts: 0.1.0-beta.1 → 0.1.0-beta.2 → …

Release candidate

npm run release:rc
# Cuts: 1.0.0-rc.1 → 1.0.0-rc.2 → …

Stable GA

npm run release
# Cuts: 1.0.0 (or next MINOR/MAJOR based on commit history)

release-it will prompt for confirmation before making any changes — you always see what it’s about to do.

Step 3 — Build and sign

After the tag is pushed, build the signed installers locally:

npm run package:mac    # macOS arm64 + x64 DMG (requires Apple signing cert)
npm run package:win    # Windows x64 NSIS installer
npm run package:linux  # Linux AppImage + deb + rpm

Attach the built artifacts to the GitHub Release that release-it created.

GitHub Secrets required (for signing)

Secret	Used for
`CSC_LINK`	macOS / Windows certificate (base64)
`CSC_KEY_PASSWORD`	Certificate password
`APPLE_ID`	Apple notarisation
`APPLE_APP_SPECIFIC_PASSWORD`	Apple notarisation
`APPLE_TEAM_ID`	Apple notarisation

Hotfix releases

For urgent fixes after a stable or beta release:

# Branch from the released tag
git checkout -b hotfix/0.1.1 v0.1.0-beta.1

# Apply fix — use conventional commit format
git commit -m "fix(engine): resolve crash on empty document upload"

# Merge back to main
git checkout main && git merge hotfix/0.1.1

# Cut the patch release
cd mira-app && npm run release

Edit this page — Open a pull request

Get Started

Core Concepts

Features

Eval Framework

Configuration

Developer Guide

Community

Reference

Release Process

Release phases

Version bump rules (after GA)

Step 1 — Write conventional commits

Step 2 — Cut a release

Beta release

Release candidate

Stable GA

Step 3 — Build and sign

GitHub Secrets required (for signing)

Hotfix releases

​Release phases

​Version bump rules (after GA)

​Step 1 — Write conventional commits

​Step 2 — Cut a release

​Beta release

​Release candidate

​Stable GA

​Step 3 — Build and sign

​GitHub Secrets required (for signing)

​Hotfix releases

Release phases

Version bump rules (after GA)

Step 1 — Write conventional commits

Step 2 — Cut a release

Beta release

Release candidate

Stable GA

Step 3 — Build and sign

GitHub Secrets required (for signing)

Hotfix releases