Release Process

Release Process

Every release produces an updated DMG attached to a tagged GitHub Release. No Apple Developer account required — the DMG is ad-hoc signed and users bypass Gatekeeper once.

Before cutting a release

• All tests pass: swift test (157 as of v0.4.0)
• App builds: xcodebuild … CODE_SIGNING_REQUIRED=NO build
• Smoke test (docs/TESTING.md — V0.1 + V0.2 + V0.3 + V0.4 sections, at minimum the highest-risk scenarios) passes on real hardware.
• Release notes drafted.
• README.md + README.zh-HK.md updated if user-visible behavior changed.

Version numbering

Setpiece follows semver-lite:

• MAJOR bumps when behavior is meaningfully different (e.g., a preset works differently).
• MINOR bumps for new features (drag-swap, animation, per-display layouts).
• PATCH bumps for bug fixes only.

V0.4 bundles V0.2 + V0.3 + V0.4 features → v0.4.0. A crash fix on top of 0.4.0 → v0.4.1.

Bump MARKETING_VERSION in the SceneApp target's build settings (Xcode → SceneApp target → General → Version). The CURRENT_PROJECT_VERSION (build number) can stay at 1.

Step-by-step (v0.4.0 as the worked example)

# 1. Ensure clean main
git checkout main
git pull
git status   # must be clean

# 2. Bump version in Xcode
#    SceneApp target → General → Version: 0.4.0
#    Commit: "chore: bump version to 0.4.0"

# 3. Regenerate the DMG (ad-hoc signed, no Developer ID needed)
./scripts/build-dmg.sh 0.4.0
#    Produces dist/Scene-0.4.0.dmg

# 4. Verify the DMG
hdiutil verify dist/Scene-0.4.0.dmg

# 5. Tag + push
git tag -a v0.4.0 -m "Setpiece V0.4.0 — Workspaces, thumbnails, vertical seeds, multilingual UI"
git push origin main
git push origin v0.4.0

# 6. Create GitHub Release with DMG attached
gh release create v0.4.0 dist/Scene-0.4.0.dmg \
    --title "Setpiece V0.4.0" \
    --notes-file RELEASE_NOTES.md

The canonical one-line pattern for cutting a release is:

./scripts/build-dmg.sh 0.4.0 && gh release create v0.4.0 dist/Scene-0.4.0.dmg --title "Setpiece V0.4.0" --notes-file RELEASE_NOTES.md

If you don't have a RELEASE_NOTES.md handy, use --notes "..." inline or open the release in the GitHub UI and edit the notes field.

Release-note template

Setpiece V<x.y.z> — <one-sentence summary>.

## Install

Download `Scene-<x.y.z>.dmg`, drag `Scene.app` to `/Applications`. First launch: right-click the app → **Open** to bypass Gatekeeper. Full walkthrough in [docs/INSTALL.md](https://github.com/ChiFungHillmanChan/setpiece/blob/main/docs/INSTALL.md).

## Requirements

- macOS 14 (Sonoma) or later
- Apple Silicon or Intel (universal binary)

## What's new

- <bullet>
- <bullet>

## Fixes

- <bullet>

## Known limitations

- <bullet>

Post-release

• Verify the release page: https://github.com/ChiFungHillmanChan/setpiece/releases
• Download the DMG from the release page on a second machine (clean-room) and run the smoke test end-to-end.
• If broken: gh release delete <tag> --yes, git tag -d <tag>, git push origin :refs/tags/<tag>. Fix + re-release.

If you ever get an Apple Developer account

Switch from ad-hoc to real Developer ID + notarization:

1. Update build-dmg.sh to use CODE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)".
2. Add a notarize step:

   xcrun notarytool submit dist/Scene-<v>.dmg --apple-id … --team-id … --password … --wait
   xcrun stapler staple dist/Scene-<v>.dmg

3. Users will no longer need the Gatekeeper right-click step. Update docs/INSTALL.md accordingly.