Add compatibility_version DSL to Formula class

[Copilot]

• Add compatibility_version DSL method to Formula class (similar to revision and version_scheme)
• Initialize @compatibility_version instance variable in Formula#initialize
• Update formula_to_dep_hash in Tab class to include compatibility_version in runtime dependencies
• Update Tab#create to store compatibility_version in source versions
• Update Dependency#installed? to check compatibility_version for dependency satisfaction
• Add tests for compatibility_version DSL in formula specs
• Add tests for compatibility_version in Tab specs
• Update Formula#to_hash to include compatibility_version in serialization
• Run typecheck, style and tests to ensure all changes work correctly
• Add formula.compatibility_version helper method for cleaner access (instead of formula.class.compatibility_version)
• Fix UsesFromMacOSDependency#installed? signature to include minimum_compatibility_version parameter

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement a compatibility_version/api_version/abi_version DSL</issue_title>
<issue_description>### Verification

• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

Provide a detailed description of the proposed feature

Formulae should have an (optional?) compatibility_version field. Alternative suggested names for this field are api_version or abi_version.

The compatibility_version field should capture suitability for use as a dependency. In particular, if a formula has a compatibility_version of 1, then it need not be upgraded when installing or upgrading dependencies as long as dependencies are known to work with versions of the formula that have compatibility_version 1.

A crucial part of this feature involves including CI testing so that:

1. compatibility_version is bumped whenever needed
2. compatibility_version is not bumped when a bump is not needed

To do the above, we would likely need to run the following dependent tests (or something similar to them):

If compatibility_version is bumped, we need to check that each dependent is broken when using the previous compatibility_version, but is not broken under the newer compatibility_version.

If compatibility_version is not bumped, then we need to check that each dependent still works when using the oldest bottles that have the same compatibility_version.

What is the motivation for the feature?

This should help minimise the number of formulae that brew {install,upgrade} foo needs to upgrade to ensure that user installs are not broken.

How will the feature be relevant to at least 90% of Homebrew users?

This should help address a pain point that many users have expressed many times over the years.

What alternatives to the feature have been considered?

Doing nothing.</issue_description>

Comments on the Issue (you are @copilot in this section)

@MikeMcQuaid Thanks for write-up @carlocab, this is great! Thoughts:

Formulae should have an (optional?) compatibility_version field.

Suggest "optional while we're rolling it out" and then "mandatory for anything that has a dependency on anything else" (i.e. if something has no dependancies: not required, if a dependency is added later: CI fails on the dependent add until it's added to the dependency).

For an initial value for this field: we could set it to the .dylib/.so "major" version for libraries and/or the major version for things that seem at least vaguely semver.

If compatibility_version is not bumped, then we need to check that each dependent still works when using the oldest bottles that have the same compatibility_version.

I think this logic is essentially the same way we detect "revision bumps" today: we download the bottle, we attempt brew linkage and brew test on that bottle and, if they both pass, no bump is needed.

The tricky bit is deciding if some dependencies need a bump and others don't (and also the cases where the linkage or test has bitrot into failing). Perhaps it should be something like >=50% of total dependencies needed bumped?

If compatibility_version is bumped, we need to check that each dependent is broken when using the previous compatibility_version, but is not broken under the newer compatibility_version.

This will be trickier. Might be a bit of a manual/human process here or brew test-bot outputs something at an earlier stage that ensures that e.g. a label is set in the PR and a bump is allowed?

Will want to make sure we socialise (very) hard that compatibility_version should NEVER be bumped except when brew test-bot says that it's needed.

The compatibility_version field should capture suitability for use as a dependency. In particular, if a formula has a compatibility_version of 1, then it need not be upgraded when installing or upgrading dependencies as long as dependencies are known to work with versions of the formula that have compatibility_version 1.

Note: this should be stored in the INSTALL_RECEIPT.json.</comment_new>
<comment_new>@carlocab

I think this logic is essentially the same way we detect "revision bumps" today: we download the bottle, we attempt brew linkage and brew test on that bottle and, if they both pass, no bump is needed.

Somewhat. The tricky part is the following. Suppose formula foo has versions 1.0, 1.1, and 1.2, and all those versions have compatibility_version 1. In our current CI setup, when we bump foo to version 1.3 but keep compatibility_version 1, we test the dependents of foo against version 1.3. However, I think we need to test dependents at least against version 1.0 as well.

The ...

Fixes #19202

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[MikeMcQuaid]

@copilot fix this CI failure:

+ brew install shellcheck shfmt
==> Fetching downloads for: shellcheck and shfmt
==> Downloading https://ghcr.io/v2/homebrew/core/shellcheck/manifests/0.11.0
==> Downloading https://ghcr.io/v2/homebrew/core/shfmt/manifests/3.12.0
Error: Your definition of `installed?` is missing these keyword arg(s): [:minimum_compatibility_version] which are defined in the method it overrides: 
 * Base definition: in Dependency at /home/linuxbrew/.linuxbrew/Homebrew/Library/Homebrew/dependency.rb:49
 * Override: in UsesFromMacOSDependency at /home/linuxbrew/.linuxbrew/Homebrew/Library/Homebrew/dependency.rb:280
Error: Process completed with exit code 1.

[Copilot]

@copilot fix this CI failure:

+ brew install shellcheck shfmt

...

Fixed in commit d4a8c2e. Updated UsesFromMacOSDependency#installed? to include the missing minimum_compatibility_version keyword argument.