docs: improve Autobump documentation

Author: AlternateRT

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:
+
+* an active `deprecate!` or `disable!` call
+* a `livecheck do` block containing a `skip` call
+* a `no_autobump!` call
+
+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.
+
+## Autobump exclusion reasons
 
-1. have a `deprecate!` or `disable!` call
-2. have a `livecheck do` block containing a `skip` call
-3. has no `no_autobump!` call
+When using `no_autobump!`, a reason for exclusion must be provided.
 
-There are other formula or cask-specific reasons listed in the Formula Cookbook and Cask Cookbook respectively.
+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):
 
-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).
+* `: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
 
-The reasons can be specified by their symbols:
+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`.

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`
 

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