Cmux Release

cmux Release

Use the /release command to prepare a new release. This will:

1. Determine the new version (bumps minor by default) 2. Gather commits since the last tag and update the changelog 3. Update CHANGELOG.md (the docs changelog page at web/app/docs/changelog/page.tsx reads from it) 4. Run ./scripts/bump-version.sh to update both versions 5. Commit, run ./scripts/release-pretag-guard.sh, tag, and push

Version bumping

./scripts/bump-version.sh
./scripts/bump-version.sh patch
./scripts/bump-version.sh major
./scripts/bump-version.sh 1.0.0

This updates both MARKETING_VERSION and CURRENT_PROJECT_VERSION. The build number is auto-incremented and is required for Sparkle auto-update to work.

Before creating a release tag, run:

./scripts/release-pretag-guard.sh

If it fails, run ./scripts/bump-version.sh, commit the build-number bump, then retry tagging.

Manual release steps if not using the command:

./scripts/release-pretag-guard.sh
git tag vX.Y.Z
git push origin vX.Y.Z
gh run watch --repo manaflow-ai/cmux

Notes

• Requires GitHub secrets: APPLE_CERTIFICATE_BASE64, APPLE_CERTIFICATE_PASSWORD, APPLE_SIGNING_IDENTITY, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID.
• The release asset is cmux-macos.dmg attached to the tag.
• README download button points to releases/latest/download/cmux-macos.dmg.
• Bump the minor version for updates unless explicitly asked otherwise.
• Update CHANGELOG.md; docs changelog is rendered from it.

Detailed reference

• Read references/release-checklist.md for a more detailed release checklist and common failure handling.

Release Checklist

This reference expands the cmux release workflow.

Default path

Prefer the /release command. It should handle:

• choosing the version
• gathering commits since the last tag
• updating CHANGELOG.md
• running ./scripts/bump-version.sh
• committing release metadata
• running ./scripts/release-pretag-guard.sh
• tagging and pushing

Version policy

Use a minor bump by default. Use patch or major only when explicitly requested or clearly justified by the release scope.

The version bump script updates both:

• MARKETING_VERSION
• CURRENT_PROJECT_VERSION

The build number must increase for Sparkle auto-update. If release-pretag-guard.sh fails because the build number is not monotonic, run the bump script, commit the build-number bump, and retry the guard.

Changelog

Update CHANGELOG.md. The docs changelog page at web/app/docs/changelog/page.tsx renders from it, so do not update a separate docs changelog source.

Keep the changelog user-facing. Mention user-visible fixes, behavior changes, and compatibility notes more prominently than internal refactors.

Tagging

Run before tagging:

./scripts/release-pretag-guard.sh

Manual tag flow:

git tag vX.Y.Z
git push origin vX.Y.Z
gh run watch --repo manaflow-ai/cmux

Release asset

The expected release asset is:

cmux-macos.dmg

The README download button points to:

releases/latest/download/cmux-macos.dmg

If the asset name changes, update every surface that assumes this path.

Required secrets

Release signing/notarization depends on:

• APPLE_CERTIFICATE_BASE64
• APPLE_CERTIFICATE_PASSWORD
• APPLE_SIGNING_IDENTITY
• APPLE_ID
• APPLE_APP_SPECIFIC_PASSWORD
• APPLE_TEAM_ID

If release automation fails before signing, inspect workflow configuration and version metadata first. If it fails during signing/notarization, inspect the secret availability and Apple account status.