Merge pull request #20393 from AlternateRT/docs-improve-autobump

docs: improve Autobump documentation

Author: MikeMcQuaid

Library/Homebrew/autobump_constants.rb

@@ -9,7 +9,7 @@
 # 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])

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`.

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`
 

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).
-
-```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"
-```
+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).
 
-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