release

Release

Run this workflow to prepare and publish a cmux release.

Workflow

1. Determine the version:

• Read MARKETING_VERSION from GhosttyTabs.xcodeproj/project.pbxproj.
• Default to a minor bump unless the user explicitly requests patch/major/specific version.

2. Create a release branch:

• git checkout -b release/vX.Y.Z

3. Gather user-facing changes and contributors since the last tag:

• git describe --tags --abbrev=0
• git log --oneline <last-tag>..HEAD --no-merges
• Keep only end-user visible changes (features, bug fixes, UX/perf behavior).
• Collect contributors: For each PR, get the author with gh pr view <N> --repo manaflow-ai/cmux --json author --jq '.author.login'. Also check linked issue reporters with gh issue view <N> --json author --jq '.author.login'.
• Build a deduplicated list of all contributor @handles.

4. Update changelogs:

• CHANGELOG.md is the source of truth: web/app/[locale]/docs/changelog/page.tsx renders the per-version bullet lists directly from it.
• Update CHANGELOG.md using categories Added, Changed, Fixed, Removed.
• Credit contributors inline (see Contributor Credits below).
• Confirm shipped scope with the user before drafting user-facing entries. A merged PR is not the same as a shipped feature: features can be behind beta toggles, internal flags, partially landed, reverted later, or otherwise not user-ready. Before writing the Added/Changed sections, list the candidate user-facing items and ask the user which are actually ready to ship in this version. Drop anything they say is not ready, plus any entries that depend on it. Re-confirm if the version, scope, or shipped surface changes mid-release.
• Mirror the curated highlights in web/app/[locale]/docs/changelog/changelog-media.ts to the same shipped scope. The docs changelog page reads its hero title and feature highlights from this file (bullets still come from CHANGELOG.md). If the user drops a feature, also remove it from the version's features and update its title so the highlights match the bullets.
• If no user-facing changes exist, confirm with the user before continuing.

5. Bump app version metadata:

• Prefer ./scripts/bump-version.sh:
  • ./scripts/bump-version.sh (minor)
  • ./scripts/bump-version.sh patch|major|X.Y.Z
• Ensure both MARKETING_VERSION and CURRENT_PROJECT_VERSION are updated.

6. Commit and push branch:

• Stage release files (changelog + version updates).
• Commit with Bump version to X.Y.Z.
• git push -u origin release/vX.Y.Z.

7. Create release PR:

• gh pr create --title "Release vX.Y.Z" --body "..."
• Include a concise changelog summary in the PR body.

8. Watch CI and resolve failures:

• gh pr checks --watch
• Fix failing checks, push, and wait for green.

9. Merge and sync main:

• gh pr merge --squash --delete-branch
• git checkout main && git pull --ff-only

10. Run the pre-tag guard, then create and push tag:

• ./scripts/release-pretag-guard.sh
• If it fails, run ./scripts/bump-version.sh, commit the build-number bump, push/merge that change, and retry the tag.
• git tag vX.Y.Z
• git push origin vX.Y.Z

11. Verify release workflow and assets:

• gh run watch --repo manaflow-ai/cmux
• Confirm release exists in GitHub Releases and includes cmux-macos.dmg.

Changelog Rules

• Include only user-visible changes that actually ship in this version. A merged PR alone is not enough: confirm with the user that each candidate feature is shipped (not behind a beta toggle, not partially landed, not deferred). When in doubt, ask before listing it.
• Exclude internal-only changes (CI, tests, docs-only edits, refactors without behavior changes).
• Write concise user-facing bullets in present tense.

Contributor Credits

Credit the people who made each release happen:

• Per-entry: Append — thanks @user! for community code contributions. Use — thanks @user for the report! for bug reporters (when different from PR author). No callout for core team (lawrencecchen, austinywang) — core work is the baseline.
• Summary: Add a ### Thanks to N contributors! section at the bottom of each release with an alphabetical list of all [@handle](https://github.com/handle) links (including core team).
• GitHub Release body: Include the same "Thanks to N contributors!" section with linked handles.