From 360ff196c48c031e77af65dcf13e5944bf50f222 Mon Sep 17 00:00:00 2001 From: AltCode <12354672+AlternateRT@users.noreply.github.com> Date: Wed, 6 Aug 2025 19:15:24 +0200 Subject: [PATCH 1/3] docs: improve Autobump documentation --- docs/Autobump.md | 31 ++++++++++++++++++++----------- docs/Cask-Cookbook.md | 14 +++++++++----- docs/Formula-Cookbook.md | 26 ++++++-------------------- 3 files changed, 35 insertions(+), 36 deletions(-) diff --git a/docs/Autobump.md b/docs/Autobump.md index 0beaf0bac0..8d9985820c 100644 --- a/docs/Autobump.md +++ b/docs/Autobump.md @@ -1,33 +1,42 @@ --- -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. +## Overview + +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 to indicate the reason. The available symbols are listed below and can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant): + +* `: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 + +These reasons can be specified by their symbols: ```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..570af29cd2 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,25 @@ 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 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). + +A custom reason can also be provided if none of the available symbols fit, for example: ```ruby no_autobump! because: "some unique reason" ``` -Refer to [Autobump](Autobump.md) page for more information about the autobump process in Homebrew. +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 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..60d2604b17 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -748,37 +748,23 @@ 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 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: +A custom reason can also be provided if none of the available symbols fit, for example: ```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 From 58884c1fac9cb221b06abaaca91e4429628f5773 Mon Sep 17 00:00:00 2001 From: AltCode <12354672+AlternateRT@users.noreply.github.com> Date: Thu, 7 Aug 2025 14:25:20 +0200 Subject: [PATCH 2/3] docs: apply suggestions from code review Co-authored-by: Mike McQuaid --- docs/Autobump.md | 9 +-------- docs/Cask-Cookbook.md | 8 +------- docs/Formula-Cookbook.md | 8 +------- 3 files changed, 3 insertions(+), 22 deletions(-) diff --git a/docs/Autobump.md b/docs/Autobump.md index 8d9985820c..81ccefcba2 100644 --- a/docs/Autobump.md +++ b/docs/Autobump.md @@ -4,8 +4,6 @@ last_review_date: "2025-08-06" # Autobump -## Overview - 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 @@ -22,12 +20,7 @@ Other formula and cask specific reasons for why a package is not autobumped are 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 to indicate the reason. The available symbols are listed below and can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant): - -* `: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 - -These reasons can be specified by their symbols: +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 diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index 570af29cd2..4b52704fcf 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -648,7 +648,7 @@ Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to writ 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. -`no_autobump!` requires a reason to be provided with the `because:` paramater. It accepts a symbol that corresponds to a preset reason, for example: +`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 @@ -656,12 +656,6 @@ no_autobump! because: :incompatible_version_format 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). -A custom reason can also be provided if none of the available symbols fit, for example: - -```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 the [Autobump](Autobump.md) page for more information about the autobump process in Homebrew. diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 60d2604b17..37f7a4b252 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -750,7 +750,7 @@ For `url`/`regex` guidelines and additional `livecheck` block examples, refer to 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. 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 symbol that corresponds to a preset reason, 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 no_autobump! because: :bumped_by_upstream @@ -758,12 +758,6 @@ no_autobump! because: :bumped_by_upstream 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). -A custom reason can also be provided if none of the available symbols fit, for example: - -```ruby -no_autobump! because: "some unique reason" -``` - See our [Autobump](Autobump.md) documentation for more information about the autobump process. ### URL download strategies From 54cfbe15ae44a8a845e4eef31ec00f8b2586395b Mon Sep 17 00:00:00 2001 From: AltCode <12354672+AlternateRT@users.noreply.github.com> Date: Thu, 7 Aug 2025 14:32:56 +0200 Subject: [PATCH 3/3] autobump_constants: improve reason descriptions --- Library/Homebrew/autobump_constants.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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])