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

# Release Process

> How MIRA versions are cut, signed, and published — from first beta to stable GA.

MIRA follows [Semantic Versioning](https://semver.org) and a phased release model: **Beta → Release Candidate → Stable**. Releases are driven by [`release-it`](https://github.com/release-please/release-it) with auto-generated changelogs from [Conventional Commits](https://www.conventionalcommits.org).

## 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](https://www.conventionalcommits.org) 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:**

```bash theme={null}
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

```bash theme={null}
cd mira-app
npm run release:beta
# Cuts: 0.1.0-beta.1 → 0.1.0-beta.2 → …
```

### Release candidate

```bash theme={null}
npm run release:rc
# Cuts: 1.0.0-rc.1 → 1.0.0-rc.2 → …
```

### Stable GA

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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
```

<Note>
  Edit this page — [Open a pull
  request](https://github.com/satyendra2013/mira-app/edit/main/docs/developer-guide/release-process.mdx)
</Note>