BrewBar/RELEASING.md

# Releasing BrewBar

## Version scheme

Semantic versioning, two or three numbers. The app is currently in a 0.x
pre-release phase:

- **0.1, 0.2, …** — pre-release iterations; anything can change between them
- **0.1.1, 0.1.2, …** — bug fixes only
- **1.0** — reserved for the first release considered stable and feature-complete

Note: Homebrew never downgrades. If a machine has a higher version installed
than the cask declares (e.g. after moving from 1.0 back to 0.1), run
`brew reinstall --cask brewbar` once instead of `brew upgrade`.

The version lives in `MARKETING_VERSION` in the Xcode project. Change it in
Xcode: target **BrewBar → General → Version** (this updates Debug and Release
together). The git tag and zip filename must match it exactly: version `1.1`
→ tag `v1.1` → `BrewBar-1.1.zip`.

## Release checklist

1. **Finish and merge the work.** Tests green, app manually verified:
   ```
   xcodebuild -project BrewBar.xcodeproj -scheme BrewBar -configuration Debug -destination "platform=macOS" test
   ```

2. **Bump the version** in Xcode (see above), commit.

3. **Build and package** (from the project root):
   ```
   xcodebuild -project BrewBar.xcodeproj -scheme BrewBar -configuration Release -destination "platform=macOS" build SYMROOT=build
   ditto -c -k --sequesterRsrc --keepParent build/Release/BrewBar.app dist/BrewBar-<VERSION>.zip
   shasum -a 256 dist/BrewBar-<VERSION>.zip
   ```
   `ditto` (not `zip`) — it preserves code signatures and Finder metadata.

4. **Update the cask** `Casks/brewbar.rb`: set `version` and paste the new
   `sha256`. Brew refuses any download whose hash doesn't match this value.

5. **Commit and push**:
   ```
   git add Casks/brewbar.rb BrewBar.xcodeproj/project.pbxproj
   git commit -m "release <VERSION>"
   git push
   ```

6. **Create the Forgejo release**: repo → Releases → New Release.
   - Tag: `v<VERSION>` (must match the cask URL), target `main`
   - Attach `dist/BrewBar-<VERSION>.zip`
   - Title: `BrewBar <VERSION>`; description: what changed since last release

7. **Upgrade on any machine**:
   ```
   brew update && brew upgrade --cask brewbar
   ```
   (`brew update` pulls the tap, sees the new cask version, `upgrade` fetches
   the release zip.)

## Notes

- The app is signed with an Apple *Development* certificate, not notarized.
  Recent Homebrew removed the `--no-quarantine` option, so on any Mac that
  did not build the app, clear the quarantine flag after install/upgrade
  (the cask prints this reminder as a caveat):
  ```
  xattr -dr com.apple.quarantine /Applications/BrewBar.app
  ```
- `dist/` and `build/` are gitignored — release zips live only in Forgejo
  releases, never in git.
- First install on a new machine:
  ```
  brew tap maxsoch/brewbar https://forgejo.socheleau.fr/maxsoch/BrewBar.git
  brew install --cask maxsoch/brewbar/brewbar
  xattr -dr com.apple.quarantine /Applications/BrewBar.app
  ```