Versioning and releases

Marbble follows semantic versioning. Prereleases carry a suffix (0.1.0-alpha.1, 0.1.0-alpha.2, …), and every release is tagged v<version>. CHANGELOG.md records each release in the Keep a Changelog format.

The version is recorded in the root Cargo.toml ([workspace.package] version, inherited by every crate) and Cargo.lock, package.json and package-lock.json, src-tauri/tauri.conf.json, and nix/package.nix. scripts/set-version.sh <version> rewrites all of them (the three workspace crates in Cargo.lock), refuses anything that isn’t a semver version, and prints the result. It needs GNU sed: on macOS install it (brew install gnu-sed) and put gsed first in PATH as sed.

To make a release:

1. Move the [Unreleased] entries in CHANGELOG.md under a new ## [<version>] - <date> heading. The release notes are taken from that section.
2. scripts/set-version.sh <version>.
3. Commit, for example git commit -am "Release <version>".
4. Tag and push the tag: git tag v<version> && git push origin main v<version>.

Pushing a v* tag runs .github/workflows/release.yml:

1. create-release makes a draft GitHub release named “Marbble v”, with the version’s CHANGELOG section plus download and unsigned-build notes. A version with a - suffix is marked as a prerelease.
2. build runs tauri-action on five runners and uploads the bundles to the draft: Linux x86_64 (ubuntu-24.04) and aarch64 (ubuntu-24.04-arm): .deb and .AppImage, plus .rpm for versions without a prerelease suffix (RPM versions can’t contain -); Windows (windows-latest): the NSIS installer (_x64-setup.exe); macOS (macos-latest): .app and .dmg for aarch64-apple-darwin and x86_64-apple-darwin.
3. publish takes the release out of draft once every build has finished, then moves the release channels (below).

Release channels

There are two, and the version decides which a release is on:

• Stable: versions without a suffix (1.2.3). GitHub marks the newest as the Latest release.
• Unstable: every release, prereleases (1.2.3-alpha.1, -beta.1, -rc.1) included, so Unstable is never behind Stable.

Each channel is also a branch, stable and unstable, that publish moves (force-pushes) to the release’s commit when the release is the newest on that channel by version; a patch to an older line leaves them alone. Nix users pin a flake input to github:JackMechem/marbble/stable or /unstable. Nothing is committed to those branches by hand; stable doesn’t exist until the first stable release. The release notes start with the channel, and the website’s Download section has a Stable/Unstable switch.

To try a change to the workflow without releasing anything, push it to the release-check branch: the same builds run, and nothing is created or published. The macOS bundles are ad-hoc signed ("signingIdentity": "-" in tauri.conf.json), with the hardened runtime and Entitlements.plist, and a step checks the signature: Apple Silicon calls an arm64 app whose bundle isn’t sealed “damaged” and won’t open it, though the linker signs the binary itself. No build is signed with a developer certificate or notarized yet.

.github/workflows/ci.yml runs on pushes to main, on pull requests and on demand, on ubuntu-24.04, windows-latest and macos-latest: npm ci, npm run build (type check and frontend build), npm test, cargo test -p daw-engine --lib, cargo test -p daw and cargo check --workspace --all-targets (so the examples must compile). On Linux it then checks cargo fmt and runs clippy with -D warnings, both on the pinned LINT_TOOLCHAIN, and runs scripts/headless-checks.sh: the headless checks that need no third-party plug-ins, on ALSA’s null device (the runner has no sound card or audio server) with a generated test tone. A separate nix job runs nix flake check, which builds the Nix package. pdc_check, freeze_check and the plug-in parts of the other checks need real plug-ins, so they don’t run in CI; run them locally.

The main branch is main on https://github.com/JackMechem/marbble.