Skip to main content
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

PhaseVersion formatPurpose
Beta0.1.0-beta.1, 0.1.0-beta.2, …Public beta — gathering real-world feedback
Release Candidate1.0.0-rc.1, 1.0.0-rc.2, …Feature-frozen, critical fixes only
Stable GA1.0.0Announced broadly — the production release
Patch1.0.1, 1.0.2, …Bug fixes after GA
Minor1.1.0, 1.2.0, …New features after GA
Major2.0.0, …Breaking changes to IPC, DB schema, or engine API

​
Version bump rules (after GA)

Change typeVersion bumpExample
Breaking change to IPC, DB schema, or engine APIMAJOR1.0.0 → 2.0.0
New feature or significant improvementMINOR1.0.0 → 1.1.0
Bug fix or documentation updatePATCH1.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:
TypeChangelog sectionVersion bump
feat:✨ FeaturesMINOR
fix:🐛 Bug FixesPATCH
perf:⚡ PerformancePATCH
docs:📚 Documentationnone
BREAKING CHANGE:💥 Breaking ChangesMAJOR
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:
  1. Bumps the version in package.json
  2. Generates a CHANGELOG.md entry from commits since the last tag
  3. Creates a git commit + tag
  4. Pushes to main
  5. 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)

SecretUsed for
CSC_LINKmacOS / Windows certificate (base64)
CSC_KEY_PASSWORDCertificate password
APPLE_IDApple notarisation
APPLE_APP_SPECIFIC_PASSWORDApple notarisation
APPLE_TEAM_IDApple 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