Document the Fizzy 3.x Homebrew upgrade path

[robzolkos]

#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.

^{Written for commit 399bf22. Summary will update on new commits.}

[Copilot]

Pull request overview

Documents the Homebrew upgrade path from Fizzy 3.x (the robzolkos/fizzy-cli formula) to the Fizzy 4.x cask (basecamp/tap/fizzy) to prevent PATH breakage during migration, and updates the Homebrew platform label to reflect Linux support.

Changes:

• Retitles the Homebrew install section to “macOS and Linux”.
• Adds explicit, ordered steps for upgrading from the 3.x formula to the 4.x cask, including rationale and a recovery command.
• Notes that brew migrate fizzy-cli does not migrate a formula-to-cask move.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Comments suppressed due to low confidence (1)

README.md:69

• The recovery command should use the fully qualified cask token for consistency with the install instructions and to avoid ambiguity if another tap provides a fizzy cask. Using basecamp/tap/fizzy makes the recovery step work even if the tap isn’t already present.

`brew unlink` first is required: a cask will not overwrite a `bin/fizzy` symlink owned by the formula, so installing the cask while the formula is still linked skips the binary and the later uninstall leaves no `fizzy` on your PATH. Recover with `brew reinstall --cask fizzy`. Note also that `brew migrate fizzy-cli`, which Homebrew suggests, is a no-op for a formula-to-cask move.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.