Releasing Minga

This document covers how to cut a release and what infrastructure supports it.

Prerequisites

GitHub Secrets

The release workflow requires these secrets in the repo's Settings > Secrets and variables > Actions:

• HOMEBREW_TAP_TOKEN: A GitHub Personal Access Token (classic) with repo scope, scoped to the jsmestad/homebrew-minga repository. The release workflow uses this to push formula and cask updates to the Homebrew tap after a stable release is published.
• APPLE_CERTIFICATE_P12: Base64-encoded Developer ID Application certificate used to sign Minga.app.
• APPLE_CERTIFICATE_PASSWORD: Password for the Developer ID certificate.
• APPLE_ID: Apple ID used for notarization.
• APPLE_APP_PASSWORD: App-specific password for the Apple ID.
• APPLE_TEAM_ID: Apple Developer Team ID used for notarization.

The built-in GITHUB_TOKEN handles creating the GitHub Release and updating CHANGELOG.md.

Cutting a Release

1. Bump the version in mix.exs (@version "x.y.z").
2. Commit and push the version bump to main via a PR.
3. Tag and push the release:

   git tag v0.1.0
   git push origin v0.1.0
   

4. The release workflow validates the tag targets the version in mix.exs, runs CI, builds binaries for all four platforms, smoke-tests each one, creates a GitHub Release with checksums, updates the Homebrew tap, and prepends the changelog.

Pre-releases

Tags with a hyphen (e.g., v0.1.0-alpha.1 or v0.1.0-rc.1) are treated as pre-releases:

• The tag's base version must match mix.exs. For example, mix.exs can stay at 0.1.0 while you cut v0.1.0-alpha.1 and v0.1.0-rc.1.
• The GitHub Release is marked as a pre-release.
• The Homebrew tap is not updated (only stable releases update the formula and cask).

What Gets Built

Homebrew Cask (macOS GUI)

The release workflow generates the minga-mac Homebrew cask for the macOS GUI app whenever a Minga.dmg artifact exists. The cask exposes the app-bundled Launch Services-aware launcher as minga, so file and directory opens reuse Minga.app by default. It also exposes minga-tui, and the primary launcher accepts --tui/--standalone, as explicit terminal escape hatches.

The standalone formula remains the default minga command on Linux. On macOS it installs the Burrito artifact as minga-tui so installing a standalone release cannot silently replace the GUI-aware primary command.

Verifying a Release

After the workflow completes:

# Download and run the binary for your platform
gh release download v0.1.0 --pattern "minga_macos_aarch64"
chmod +x minga_macos_aarch64
./minga_macos_aarch64 --version

# Install the standalone TUI on Linux (stable releases only)
brew install jsmestad/minga/minga
minga --version

# Install the macOS app and GUI-aware primary launcher
brew install --cask jsmestad/minga/minga-mac
minga .
minga --tui README.md

Burrito

Minga uses Burrito to package the Elixir release as a self-extracting binary. Distribution cookies must be present as RELEASE_COOKIE before a Burrito process starts; setting only MINGA_COOKIE inside application code is too late because the VM already exists. Direct execution of a downloaded raw Burrito artifact therefore requires RELEASE_COOKIE whenever distribution will be enabled. The Homebrew and bundled GUI/TUI wrappers map --cookie-file, MINGA_COOKIE, and RELEASE_COOKIE in that precedence order before VM startup. Non-distributed wrapper boots clear inherited ERL_AFLAGS, ERL_FLAGS, ERL_ZFLAGS, ELIXIR_ERL_OPTIONS, and RELEASE_VM_ARGS, then install a fresh random fallback cookie so a local editor cannot accidentally inherit distribution or the baked-in release cookie.

Burrito currently requires Zig 0.15.2 for the wrap step, while Minga's Zig renderer uses the project Zig version from .tool-versions. The release workflow compiles the project with ZIG_VERSION, switches to BURRITO_ZIG_VERSION, then runs mix release minga --no-compile so Burrito can wrap the already-compiled release. When upgrading Burrito, check Burrito.get_versions/0, update BURRITO_ZIG_VERSION if needed, and run mix deps.get to update mix.lock.