Documentation Index
Fetch the complete documentation index at: https://docs.mira-app.dev/llms.txt
Use this file to discover all available pages before exploring further.
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]
| 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 |
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
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
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
