Rename through deprecation?

[walles]

Output of brew config

HOMEBREW_VERSION: 4.5.13-78-g75aee5e
ORIGIN: https://github.com/Homebrew/brew.git
HEAD: 75aee5ec5ccb7cebc05086fde14a640452c44e38
Last commit: 5 days ago
Branch: main
Core tap HEAD: 3a935c0996999bb5fa36df6ec152563b3d92dca6
Core tap last commit: 3 months ago
Core tap JSON: 05 Aug 15:39 UTC
Core cask tap HEAD: 39e4baca231c013729863c84e53cfa7c23e9da33
Core cask tap last commit: 3 months ago
Core cask tap JSON: 05 Aug 15:39 UTC
HOMEBREW_PREFIX: /usr/local
HOMEBREW_CASK_OPTS: []
HOMEBREW_DISPLAY: /private/tmp/com.apple.launchd.1slk3D6on9/org.macosforge.xquartz:0
HOMEBREW_EDITOR: code -w
HOMEBREW_GITHUB_API_TOKEN: set
HOMEBREW_MAKE_JOBS: 16
HOMEBREW_SORBET_RUNTIME: set
Homebrew Ruby: 3.4.5 => /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/3.4.5/bin/ruby
CPU: 16-core 64-bit kabylake
Clang: 17.0.0 build 1700
Git: 2.50.1 => /usr/local/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 15.5-x86_64
CLT: 16.4.0.0.1.1747106510
Xcode: 16.4

Output of brew doctor

Your system is ready to brew.

Description of issue

I'm considering renaming https://formulae.brew.sh/formula/moar (and its included binary) to moor.

Can I do that by:

1. Adding a new formula for moor
2. Deprecating the legacy moar formula, referring to the new formula as its replacement?

If I just rename the formula, I'm afraid people who are used to typing moar won't understand what happened and why moar doesn't exist any more.

With a deprecation + replacement, I'm hoping the new name should be more obvious.

[SMillerDev]

If you add a rename it will redirect people to the new name, so I think that's a much better indicator.

[walles]

Let's say Moira is an existing user of moar.

With a rename, won't this happen?

• Before brew upgrade, Moira does moar /etc/services as she always does, and it works
• brew upgrade removes the moar binary and installs a moor binary instead
• moar /etc/services now doesn't work any more and it's not obvious to Moira why

With a deprecation, this is what I'd be hoping for

• Before brew upgrade, Moira does moar /etc/services as she always does, and it works
• brew upgrade warns Moira that she should be using moor instead
• moar /etc/services still works as before
• Moira knows she needs to switch to moor instead

Which experience would be best for Moira?

[walles]

Actually, when thinking about this a bit more, I think I should just:

• Rename the package and the binary
• Add a transition moar binary in the renamed package that prints a warning about the rename to stderr and then execs moor
• At some point in the future, remove the transition binary

[gromgit]

Deprecation only changes the formula name, it doesn't help with executable renames. Also, folks tend not to read the output of brew upgrade too closely, unless it says "ERROR" in red text (and sometimes not even then).

Since you're the upstream in question, I suggest adding a moar script shim that directs your users to run moor ... instead, so they know what to do next. That will work with any packaging mechanism, i.e. it'll work just as well with RPMs, DEBs, and whatever other package format your users decide to distribute your project as.