Document the Fizzy 3.x Homebrew upgrade path

Merged
RO
3mo ago
+13-1

#194 replaced the stale Homebrew block, but didn't carry over upgrade instructions — so this repo currently has no guidance for anyone on the robzolkos/fizzy-cli tap. The tap's own README is the only place it exists.

Why the order matters

This isn't obvious, and getting it wrong leaves users with no fizzy on PATH. Verified on a real 3.0.3 install:

A cask will not overwrite a bin/fizzy symlink owned by a formula. Installing the cask while fizzy-cli is still linked silently skips the binary — payload lands in the Caskroom, nothing links to it:

$ brew install --cask basecamp/tap/fizzy
$ brew list --cask --versions fizzy
fizzy 4.0.0
$ fizzy --version
fizzy version v3.0.3          # still the old keg

Uninstalling the formula then removes the only fizzy that existed:

$ brew uninstall --formula --force fizzy-cli
$ which fizzy
fizzy not found

brew unlink fizzy-cli first avoids this, mirroring what Homebrew's own automatic migration does — cmd/update_report/reporter.rb runs unlink → cleanup → install --cask in that order precisely so the cask can claim the path. Recovery, if someone already hit it, is brew reinstall --cask fizzy.

brew migrate doesn't work here

Homebrew prints brew migrate fizzy-cli to every user who hits the untrusted-tap path. It's a no-op for a formula-to-cask move:

$ brew migrate fizzy-cli
Warning: Treating fizzy-cli as a formula. For the cask, use basecamp/tap/fizzy
or specify the `--cask` flag.

Exits without migrating. Since users are told to run it, the README now says explicitly that it does nothing.

Also

Retitles the section Homebrew (macOS and Linux) — the generated cask ships on_linux blocks for amd64 and arm64, so the macOS-only label undersold it.

Related

Same correction landed in the tap README via robzolkos/homebrew-fizzy-cli#3, and the v4.0.0 release notes now carry an "Upgrading from Fizzy 3.x" section with the same sequence.

Summary by cubic

Document the Homebrew upgrade path from Fizzy 3.x (robzolkos/fizzy-cli formula) to the basecamp/tap/fizzy cask, and clarify that Homebrew never auto-taps third‑party taps. Retitles the Homebrew section to “macOS and Linux” to reflect support on both platforms.

  • Migration
    • Exact order for moving from 3.x: brew tap basecamp/tap → brew unlink fizzy-cli → brew install --cask basecamp/tap/fizzy → brew uninstall --formula --force fizzy-cli → brew untap robzolkos/fizzy-cli.
    • States brew tap basecamp/tap is required; Homebrew does not auto-tap third‑party taps during migration or from a fully‑qualified install.
    • Explains why unlink must happen first (a cask won’t overwrite the formula’s bin/fizzy symlink) and how to recover: brew reinstall --cask fizzy.
    • Notes brew migrate fizzy-cli is a no‑op for formula‑to‑cask moves.