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

docs: improve Autobump documentation

Browse Source
This commit is contained in:
AltCode 2025-08-06 19:15:24 +02:00
parent 726f83c4a8
commit 360ff196c4
No known key found for this signature in database
3 changed files with 35 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/Autobump.md
View File

@ -1,33 +1,42 @@
--- ---
last_review_date: "2025-06-16" last_review_date: "2025-08-06"
--- ---
# Autobump # 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 ## 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 * an active `deprecate!` or `disable!` call
2. have a `livecheck do` block containing a `skip` call * a `livecheck do` block containing a `skip` call
3. has no `no_autobump!` 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 ```ruby
no_autobump! because: :bumped_by_upstream 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 ```ruby
no_autobump! because: "some unique reason" 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 # Cask Cookbook
@ -646,21 +646,25 @@ Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to writ
### Stanza: `no_autobump!` ### 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 ```ruby
no_autobump! because: :incompatible_version_format 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 ```ruby
no_autobump! because: "some unique reason" 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` ### Stanza: `name`

26
docs/Formula-Cookbook.md
View File

@ -748,37 +748,23 @@ For `url`/`regex` guidelines and additional `livecheck` block examples, refer to
### Excluding formula from autobumping ### 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 ```ruby
class Foo < Formula no_autobump! because: :bumped_by_upstream
# ...
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
``` ```
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 A custom reason can also be provided if none of the available symbols fit, for example:
no_autobump! because: :incompatible_version_format
```
A custom reason can be provided if none of the available symbols fits:
```ruby ```ruby
no_autobump! because: "some unique reason" 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 ### URL download strategies