Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 0 additions & 106 deletions .claude/commands/release-local.md

This file was deleted.

107 changes: 0 additions & 107 deletions .claude/commands/release-nightly.md

This file was deleted.

85 changes: 48 additions & 37 deletions .claude/commands/release.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,24 @@
# Release

Prepare a new release for cmux. This command updates the changelog, bumps the version, creates a PR, monitors CI, and then merges and tags.
Programa ships from a single continuously-updating lane: every commit on `main` that passes the
`CI` GitHub Actions workflow is automatically built, signed, notarized, and published as the
latest release by `.github/workflows/release.yml` (triggered via `workflow_run` on `CI`
completing with `conclusion: success`). There is no nightly/beta channel and no manual publish
step for ordinary changes — merge to `main`, let CI go green, and the release ships itself.

This command is only for **milestone marketing-version bumps** (e.g. `0.15.0` → `0.16.0`), which
are still done manually via a PR + optional `vX.Y.Z` tag marker.

## When to use this

- The user wants to bump the marketing version and record a changelog entry for a milestone.
- Not needed for routine fixes/features — those ship automatically on the next green `main` build.

## Steps

1. **Determine the new version number**
- Get the current version from `GhosttyTabs.xcodeproj/project.pbxproj` (look for `MARKETING_VERSION`)
- Bump the minor version unless the user specifies otherwise (e.g., 0.12.0 → 0.13.0)
- Bump the minor version unless the user specifies otherwise (e.g., 0.15.0 → 0.16.0)

2. **Create a release branch**
- Create branch: `git checkout -b release/vX.Y.Z`
Expand All @@ -18,11 +30,11 @@ Prepare a new release for cmux. This command updates the changelog, bumps the ve
- Categorize changes into: Added, Changed, Fixed, Removed
- **Collect contributors:** For each PR referenced in the commits, get the author:
```bash
gh pr view <N> --repo manaflow-ai/cmux --json author --jq '.author.login'
gh pr view <N> --repo darkroomengineering/programa --json author --jq '.author.login'
```
- Also check for linked issue reporters (the person who filed the bug):
```bash
gh issue view <N> --repo manaflow-ai/cmux --json author --jq '.author.login'
gh issue view <N> --repo darkroomengineering/programa --json author --jq '.author.login'
```
- Build a deduplicated list of all contributor `@handle`s for the release

Expand All @@ -31,49 +43,50 @@ Prepare a new release for cmux. This command updates the changelog, bumps the ve
- **Only include changes that affect the end-user experience** - things users will see, feel, or interact with
- Write clear, user-facing descriptions (not raw commit messages)
- **Credit contributors inline** (see Contributor Credits below)
- Also update `docs-site/content/docs/changelog.mdx` with the same content
- If there are no user-facing changes, ask the user if they still want to release
- Also update the docs changelog page at `web/app/docs/changelog/page.tsx` with the same content
- If there are no user-facing changes, ask the user if they still want to bump the version

5. **Bump the version in Xcode project**
- Update all occurrences of `MARKETING_VERSION` in `GhosttyTabs.xcodeproj/project.pbxproj`
- There are typically 4 occurrences (Debug/Release for main app and CLI)
5. **Bump the version**
- Run `./scripts/bump-version.sh` (bumps minor by default; accepts `patch`, `major`, or an explicit version)

6. **Commit and push the release branch**
- Stage: `CHANGELOG.md`, `docs-site/content/docs/changelog.mdx`, `GhosttyTabs.xcodeproj/project.pbxproj`
- Stage: `CHANGELOG.md`, `web/app/docs/changelog/page.tsx`, `GhosttyTabs.xcodeproj/project.pbxproj`
- Commit message: `Bump version to X.Y.Z`
- Push: `git push -u origin release/vX.Y.Z`

7. **Create a pull request**
- Create PR: `gh pr create --title "Release vX.Y.Z" --body "...changelog summary..."`
- Create PR: `gh pr create --title "Bump version to vX.Y.Z" --body "...changelog summary..."`
- Include the changelog entries in the PR body

8. **Monitor CI**
- Watch the CI workflow: `gh pr checks --watch`
- Watch: `gh pr checks --watch`
- If CI fails, fix the issues and push again
- Wait for all checks to pass before proceeding

9. **Merge the PR**
- Merge: `gh pr merge --squash --delete-branch`
- Switch back to main: `git checkout main && git pull`

10. **Create and push the tag**
- Create tag: `git tag vX.Y.Z`
- Push tag: `git push origin vX.Y.Z`
- Once `CI` goes green on this merge commit, `release.yml` auto-ships it as the new latest
release — no further action is required.

10. **(Optional) Tag the milestone**
- If you want a durable `vX.Y.Z` marker in the release history (in addition to the
auto-shipped release), tag it:
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```
- This also triggers `release.yml` via its `push: tags: v*` trigger, publishing under that
exact tag.

11. **Monitor the release workflow**
- Watch: `gh run watch --repo manaflow-ai/cmux`
- Verify the release appears at: https://github.com/manaflow-ai/cmux/releases
- Check that the DMG is attached to the release

12. **Verify homebrew cask update**
- The "Update Homebrew Cask" workflow triggers automatically after the release workflow completes
- Watch: `gh run list --workflow=update-homebrew.yml --limit=1` and `gh run watch`
- Verify: `cd homebrew-cmux && git pull && grep version Casks/cmux.rb`
- Run `bash tests/test_homebrew_sha.sh` to confirm the SHA matches
- Watch: `gh run watch --repo darkroomengineering/programa`
- Verify the release appears at: https://github.com/darkroomengineering/programa/releases
- Check that `programa-macos.dmg` is attached to the release

13. **Notify**
- On success: `say "cmux release complete"`
- On failure: `say "cmux release failed"`
12. **Notify**
- On success: `say "programa release complete"`
- On failure: `say "programa release failed"`

## Changelog Guidelines

Expand Down Expand Up @@ -106,7 +119,6 @@ Credit the people who made each release happen. This builds community and encour
**Per-entry attribution** — append contributor credit after each changelog bullet:
- For code contributions (PR author): `— thanks @user!`
- For bug reports (issue reporter, if different from PR author): `— thanks @reporter for the report!`
- Core team (`lawrencecchen`, `austinywang`) contributions get no per-entry callout — core work is the baseline

**Summary section** — add a "Thanks to N contributors!" section at the bottom of each release:
```markdown
Expand All @@ -115,7 +127,7 @@ Credit the people who made each release happen. This builds community and encour
- [@user1](https://github.com/user1)
- [@user2](https://github.com/user2)
```
- List all contributors alphabetically by GitHub handle (including core team)
- List all contributors alphabetically by GitHub handle
- Link each handle to their GitHub profile
- Include everyone: PR authors, issue reporters, anyone whose work is in the release

Expand All @@ -124,22 +136,21 @@ Credit the people who made each release happen. This builds community and encour
## Example Changelog Entry

```markdown
## [0.13.0] - 2025-01-30
## [0.16.0] - 2026-07-07

### Added
- New keyboard shortcut for quick tab switching ([#42](https://github.com/manaflow-ai/cmux/pull/42)) — thanks @contributor!
- New keyboard shortcut for quick tab switching ([#42](https://github.com/darkroomengineering/programa/pull/42)) — thanks @contributor!

### Fixed
- Memory leak when closing split panes ([#38](https://github.com/manaflow-ai/cmux/pull/38)) — thanks @fixer!
- Notification badges not clearing properly ([#35](https://github.com/manaflow-ai/cmux/pull/35)) — thanks @reporter for the report!
- Memory leak when closing split panes ([#38](https://github.com/darkroomengineering/programa/pull/38)) — thanks @fixer!
- Notification badges not clearing properly ([#35](https://github.com/darkroomengineering/programa/pull/35)) — thanks @reporter for the report!

### Changed
- Improved terminal rendering performance ([#40](https://github.com/manaflow-ai/cmux/pull/40))
- Improved terminal rendering performance ([#40](https://github.com/darkroomengineering/programa/pull/40))

### Thanks to 4 contributors!
### Thanks to 3 contributors!

- [@contributor](https://github.com/contributor)
- [@fixer](https://github.com/fixer)
- [@lawrencechen](https://github.com/lawrencechen)
- [@reporter](https://github.com/reporter)
```
12 changes: 0 additions & 12 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,18 +46,6 @@ body:
validations:
required: true

- type: dropdown
id: nightly-repro
attributes:
label: Can you reproduce this on cmux NIGHTLY?
description: "Please test with the latest NIGHTLY build first: https://github.com/manaflow-ai/cmux?tab=readme-ov-file#nightly-builds"
options:
- Yes, it still reproduces on NIGHTLY
- No, it does not reproduce on NIGHTLY
- I could not test NIGHTLY
validations:
required: true

- type: textarea
id: description
attributes:
Expand Down
Loading
Loading