admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

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

Browse Source 
docs: improve Autobump documentation
This commit is contained in:
Mike McQuaid 2025-08-07 12:50:11 +00:00 committed by GitHub
commit a10e4230b4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 26 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Library/Homebrew/autobump_constants.rb
View File

@ -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])

24
docs/Autobump.md
View File

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

14
docs/Cask-Cookbook.md
View File

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

30
docs/Formula-Cookbook.md
View File

@ -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