Add bump-compatibility-version command

[p-linnane]

compatibility_version was recently added to the formula DSL, and brew audit now enforces it against dependent revision bumps. There was no tooling to set it, though, so maintainers had to hand-edit the stanza. This adds brew bump-compatibility-version, mirroring the long-standing brew bump-revision, to create a commit that increments a formula's compatibility_version (or adds compatibility_version 1 when none is present). It supports the same --dry-run, --write-only and --message options, and the homebrew-core maintainer guide now suggests it alongside bump-revision when a dependent needs a rebuild.

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include Hyperfine benchmarks.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• AI was used to generate or assist with generating this PR.

Claude Code (Opus 4.8) prepared this PR: reviewed the new command against repo conventions, fixed docs line-wrapping, and regenerated the manpage and completions. I verified with brew lgtm and by running brew bump-compatibility-version --dry-run on formulae with and without an existing compatibility_version.

---

[bevanjkay]

Thanks @p-linnane - I had wondered about adding a --for-compatibility <formula> flag to bump-revision to do it all in one go, but this isn't really any more cumbersome.

[Copilot]

Pull request overview

Adds a new developer command, brew bump-compatibility-version, to automate incrementing a formula’s compatibility_version (or adding compatibility_version 1 when absent), aligning with the existing bump-revision workflow and reducing manual formula edits now that brew audit enforces this relationship.

Changes:

• Implement brew bump-compatibility-version with --dry-run, --write-only, and --message options, mirroring bump-revision behavior.
• Add unit tests and Sorbet RBI for the new command.
• Update documentation, manpage, and shell completions to expose the new command and recommend it in maintainer guidance.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
manpages/brew.1	Documents the new bump-compatibility-version command in the generated manpage.
Library/Homebrew/dev-cmd/bump-compatibility-version.rb	Implements the new dev command, using Utils::AST::FormulaAST to add/replace the stanza and optionally commit.
Library/Homebrew/test/dev-cmd/bump-compatibility-version_spec.rb	Adds coverage for adding and incrementing compatibility_version in --write-only mode.
Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/bump_compatibility_version.rbi	Adds generated RBI for the new command’s args methods.
docs/Manpage.md	Documents the new command in the Markdown manpage source.
docs/Homebrew-homebrew-core-Maintainer-Guide.md	Updates maintainer guidance to suggest bumping compatibility_version when dependent revision bumps are needed.
docs/Formula-Cookbook.md	Points readers to brew bump-compatibility-version as the mechanical way to bump compatibility_version.
completions/zsh/_brew	Adds zsh completions for the new command and registers it in the command list.
completions/fish/brew.fish	Adds fish completions for the new command.
completions/bash/brew	Adds bash completions for the new command and dispatch wiring.
completions/internal_commands_list.txt	Registers the new command for completion generation and command suggestion.

Files not reviewed (1)

• Library/Homebrew/sorbet/rbi/dsl/homebrew/dev_cmd/bump_compatibility_version.rbi: File type not supported

---

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

[MikeMcQuaid]

Can you see how much more/less code it is as a bump-revision flag instead? Feels like a full new command for this is not terrible but it's quite a heavy diff for essentially the same operation.

[p-linnane]

Can you see how much more/less code it is as a bump-revision flag instead? Feels like a full new command for this is not terrible but it's quite a heavy diff for essentially the same operation.

It would be ~150 fewer lines, but at the cost of discoverability and cramming something related, but different into an existing command.

[MikeMcQuaid]

It would be ~150 fewer lines, but at the cost of discoverability and cramming something related, but different into an existing command.

Convinced me. Ship it