diff --git a/Library/Homebrew/autobump_constants.rb b/Library/Homebrew/autobump_constants.rb index baf7ecdf5a..31ce8d2648 100644 --- a/Library/Homebrew/autobump_constants.rb +++ b/Library/Homebrew/autobump_constants.rb @@ -9,7 +9,7 @@ NO_AUTOBUMP_REASONS_INTERNAL = T.let({ # The valid symbols for passing to `no_autobump!` in a `Formula` or `Cask`. # @api public NO_AUTOBUMP_REASONS_LIST = T.let({ - incompatible_version_format: "incompatible version format", - bumped_by_upstream: "bumped by upstream", + incompatible_version_format: "the package has a version format that can only be updated manually", + bumped_by_upstream: "updates to the package are handled by the upstream developers", requires_manual_review: "a manual review of this package is required for inclusion in autobump", }.merge(NO_AUTOBUMP_REASONS_INTERNAL).freeze, T::Hash[Symbol, String]) diff --git a/docs/Autobump.md b/docs/Autobump.md index 0beaf0bac0..81ccefcba2 100644 --- a/docs/Autobump.md +++ b/docs/Autobump.md @@ -1,33 +1,35 @@ --- -last_review_date: "2025-06-16" +last_review_date: "2025-08-06" --- # Autobump -[BrewTestBot](BrewTestBot.md) automatically checks for available updates of packages that are in Homebrew's "autobump list" for official repositories. These packages should not have to be bumped (i.e versions increased) manually by a contributor. Instead, every 3 hours a GitHub Action opens a new pull request to upgrade to the latest version of a formula/cask, if needed. +In official repositories, [BrewTestBot](BrewTestBot.md) automatically checks for available updates to packages that are in Homebrew's "autobump list". These packages do not need to be bumped (i.e. have their version number increased) manually by a contributor. Instead, every 3 hours, a GitHub Action opens a new pull request to upgrade them to the latest version, if needed. ## Excluding packages from autobumping -By default, all new formulae and casks from [Homebrew/core](https://github.com/Homebrew/homebrew-core) and [Homebrew/cask](https://github.com/Homebrew/homebrew-cask) repositories are autobumped. To exclude a package from being autobumped, it must: +By default, all new formulae and casks from the [Homebrew/core](https://github.com/Homebrew/homebrew-core) and [Homebrew/cask](https://github.com/Homebrew/homebrew-cask) repositories are autobumped. To exclude a package from the autobump list, it must have one of the following: -1. have a `deprecate!` or `disable!` call -2. have a `livecheck do` block containing a `skip` call -3. has no `no_autobump!` call +* an active `deprecate!` or `disable!` call +* a `livecheck do` block containing a `skip` call +* a `no_autobump!` call -There are other formula or cask-specific reasons listed in the Formula Cookbook and Cask Cookbook respectively. +Other formula and cask specific reasons for why a package is not autobumped are listed in the [Formula Cookbook](Formula-Cookbook.md) and [Cask Cookbook](Cask-Cookbook.md) respectively. -To use `no_autobump!`, a reason for exclusion must be provided. We prefer use of one of the supported symbols. These can be found in the [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). +## Autobump exclusion reasons -The reasons can be specified by their symbols: +When using `no_autobump!`, a reason for exclusion must be provided. + +There are two ways to indicate the reason. The preferred way is to use a pre-existing symbol, which can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant), for example: ```ruby no_autobump! because: :bumped_by_upstream ``` -If none of the existing reasons fit, a custom reason can be provided as a string: +If these pre-existing reasons do not fit, a custom reason can be specified: ```ruby no_autobump! because: "some unique reason" ``` -If there are multiple packages with a similar custom reason, it be added to `NO_AUTOBUMP_REASONS_LIST`. +If there are multiple packages with a similar custom reason, it can be added as a new symbol to `NO_AUTOBUMP_REASONS_LIST`. diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index 32684f0fef..4b52704fcf 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -1,5 +1,5 @@ --- -last_review_date: 2025-05-18 +last_review_date: "2025-05-18" --- # Cask Cookbook @@ -646,21 +646,19 @@ Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to writ ### Stanza: `no_autobump!` -The `no_autobump!` stanza excludes the cask for autobump list. That means the future updates will be handled by Homebrew contributors rather than by an automated process. +The `no_autobump!` stanza excludes a cask from the autobump list. This means all updates are to be handled manually by submitting pull requests to the `Homebrew/homebrew-cask` repository. -To use this stanza, a reason must be provided. The preferred way is to use one of the available symbols. These symbols can be found in the [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). +`no_autobump!` requires a reason to be provided with the `because:` paramater. It accepts a string or a symbol that corresponds to a preset reason, for example: ```ruby no_autobump! because: :incompatible_version_format ``` -A custom reason can be provided if none of the available symbols fits: +A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). -```ruby -no_autobump! because: "some unique reason" -``` +Casks that use `strategy :extract_plist` in their `livecheck` block or have `version :latest` are always excluded from the autobump list and do not require `no_autobump!` to be declared. -Refer to [Autobump](Autobump.md) page for more information about the autobump process in Homebrew. +Refer to the [Autobump](Autobump.md) page for more information about the autobump process in Homebrew. ### Stanza: `name` diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index b3bbaf8719..37f7a4b252 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -748,37 +748,17 @@ For `url`/`regex` guidelines and additional `livecheck` block examples, refer to ### Excluding formula from autobumping -By default, all new formulae in the Homebrew/core repository are autobumped. It means that future updates will be handled automatically by Homebrew CI jobs, and contributors do not have to do it manually. +By default, all new formulae in the `Homebrew/homebrew-core` repository are autobumped. This means that future updates are handled automatically by Homebrew CI jobs, and contributors do not have to submit pull requests. -Sometimes, we want to exclude a formula from this list, for one reason or another. It can be done by adding the `no_autobump!` method in the formula definition, for example: +Sometimes, we want to exclude a formula from this list, for one reason or another. This can be done by adding the `no_autobump!` method in the formula definition; a reason must be provided with the `because:` parameter. It accepts a string or a symbol that corresponds to a preset reason, for example: ```ruby -class Foo < Formula - # ... - url "https://example.com/foo-1.0.tar.gz" - - livecheck do - url "https://example.com/foo/download.html" - regex(/href=.*?foo[._-]v?(\d+(?:\.\d+)+)\.t/i) - end - - no_autobump! because: :bumped_by_upstream -end +no_autobump! because: :bumped_by_upstream ``` -To use this method, a reason must be provided. The preferred way is to use one of the available symbols. These reasons can be found in the [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). +A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). -```ruby -no_autobump! because: :incompatible_version_format -``` - -A custom reason can be provided if none of the available symbols fits: - -```ruby -no_autobump! because: "some unique reason" -``` - -More information about the autobump process can be found on the [Autobump](Autobump.md) page. +See our [Autobump](Autobump.md) documentation for more information about the autobump process. ### URL download strategies