mirror of
https://github.com/Homebrew/brew.git
synced 2025-07-14 16:09:03 +08:00
docs: add autobump-related documentation
Signed-off-by: botantony <antonsm21@gmail.com>
This commit is contained in:
botantony
parent
6301c2d31f
commit
0dc48348af
42
docs/Autobump.md
Normal file
42
docs/Autobump.md
Normal file
@ -0,0 +1,42 @@
|
||||
---
|
||||
last_review_date: "2025-06-16"
|
||||
---
|
||||
|
||||
# Autobump
|
||||
|
||||
[BrewTestBot](BrewTestBot.md) automatically checks for available updates of packages in autobump list. It means that some formulae and casks in official repositories do not have to be bumped manually by a contributor. Instead, every 3 hours, a GitHub Action ensures and a new pull request is opened if Homebrew does not provide the latest version of a formula/cask.
|
||||
|
||||
## Excluding packages from autobump list
|
||||
|
||||
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 added to the list. To exclude a package from the list, it should satisfy one of the following:
|
||||
|
||||
1. The package is deprecated or disabled.
|
||||
2. The The Livecheck block has a `skip` method.
|
||||
3. It has a `no_autobump!` method/stanza.
|
||||
|
||||
There are maybe other formula-specific or cask-specific reasons that are not listed here. Please, refer to the respective documentation to learn more about it.
|
||||
|
||||
To use the `no_autobump!`, a reason for exclusion **must** be provided. The preferred way to set the reason is to use one of the available supported symbols. The list of these symbols can be found in the [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant) constants:
|
||||
|
||||
* `:incompatible_version_format`: This reason is used when the `brew bump` command cannot determine a version for the URL or update it. For example, if a tarball with the source code has a complex URL like `https://example.com/download/<major-version>/<minor-version>/foo-<full-version>-<git-commit>.tar.gz`, Homebrew wouldn't be able to replace the old URL with the new one automatically.
|
||||
* `:bumped_by_upstream`: Some developers whose programs are available in Homebrew want to take care of the updates themselves or even set up a CI action that does this. This `no_autobump!` reason exists for such cases.
|
||||
* `:requires_manual_review`: This is a temporary reason and expected to be deprecated in the future. It indicates that this package was not in the `autobump.txt` file before the new autobump list was introduced.
|
||||
|
||||
Some `no_autobump!` reasons also appear in the list but should not be used directly:
|
||||
|
||||
* `:extract_plist`: This reason is set if `livecheck` uses the `:extract_plist` strategy.
|
||||
* `:latest_version`: This reason is set if `version` is set to `:latest`.
|
||||
|
||||
The reasons can be specified by their symbols:
|
||||
|
||||
```ruby
|
||||
no_autobump! because: :bumped_by_upstream
|
||||
```
|
||||
|
||||
If none of the reasons from above fit, a custom reason can be provided as a string:
|
||||
|
||||
```ruby
|
||||
no_autobump! because: "some unique reason"
|
||||
```
|
||||
|
||||
If there are multiple packages with a similar custom reason, it should be considered to add it to `NO_AUTOBUMP_REASONS_LIST`.
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
last_review_date: 2025-05-28
|
||||
last_review_date: 2025-06-23
|
||||
---
|
||||
|
||||
# `brew livecheck`
|
||||
@ -438,6 +438,8 @@ livecheck do
|
||||
end
|
||||
```
|
||||
|
||||
Note that if a package uses this livecheck strategy it will be excluded from [autobump list](Autobump.md).
|
||||
|
||||
### `throttle`
|
||||
|
||||
For software with extremely frequent releases that don't all need to be published as formula/cask updates, livecheck can be set to reduce how many versions it surfaces by using `throttle`. In this example, only versions whose last component is divisible by 10 will be returned.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
last_review_date: 2025-05-18
|
||||
last_review_date: "2025-06-16"
|
||||
---
|
||||
|
||||
# Cask Cookbook
|
||||
@ -56,6 +56,8 @@ Having a common order for stanzas makes casks easier to update and parse. Below
|
||||
|
||||
livecheck
|
||||
|
||||
no_autobump!
|
||||
|
||||
deprecate!
|
||||
disable!
|
||||
|
||||
@ -173,6 +175,7 @@ Each cask must declare one or more [artifacts](https://rubydoc.brew.sh/Cask/Arti
|
||||
| `container nested:` | no | Relative path to an inner container that must be extracted before moving on with the installation. This allows for support of `.dmg` inside `.tar`, `.zip` inside `.dmg`, etc. (Example: [blocs.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/b/blocs.rb#L17-L19)) |
|
||||
| `container type:` | no | Symbol to override container-type autodetect. May be one of: `:air`, `:bz2`, `:cab`, `:dmg`, `:generic_unar`, `:gzip`, `:otf`, `:pkg`, `:rar`, `:seven_zip`, `:sit`, `:tar`, `:ttf`, `:xar`, `:zip`, `:naked`. (Example: [parse.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/p/parse.rb#L10)) |
|
||||
| `auto_updates` | no | `true`. Asserts that the cask artifacts auto-update. Use if `Check for Updates…` or similar is present in an app menu, but not if it only opens a webpage and does not do the download and installation for you. |
|
||||
| [`no_autobump!`](#stanza-no_autobump) | no | Allowed symbol or a string. Excludes cask from autobump list if set. |
|
||||
|
||||
## Stanza descriptions
|
||||
|
||||
@ -641,6 +644,28 @@ Every `livecheck` block must contain a `url`, which can be either a string or a
|
||||
|
||||
Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to write a `livecheck` block.
|
||||
|
||||
### 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.
|
||||
|
||||
To use this stanza, a reason must be provided. The preferred way is to use one of the available symbols:
|
||||
|
||||
* `:incompatible_version_format`: This reason is used when the `brew bump` command cannot determine a version for the URL or update it.
|
||||
* `:bumped_by_upstream`: Some developers whose programs are available in Homebrew want to take care of the updates themselves or even set up a CI action that does this. This `no_autobump!` reason exists for such cases.
|
||||
* `:requires_manual_review`: This is a temporary reason and expected to be deprecated in the future. It indicates that this package was not in the `autobump.txt` file before the new autobump list was introduced.
|
||||
|
||||
```ruby
|
||||
no_autobump! because: :incompatible_version_format
|
||||
```
|
||||
|
||||
The full list of available symbols is stored in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant) constant. A custom reason can be provided if none of the available symbols fits:
|
||||
|
||||
```ruby
|
||||
no_autobump! because: "some unique reason"
|
||||
```
|
||||
|
||||
Refer to [Autobump](Autobump.md) page for more information about the autobump process in Homebrew.
|
||||
|
||||
### Stanza: `name`
|
||||
|
||||
`name` accepts a UTF-8 string defining the name of the software, including capitalization and punctuation. It is used to help with searchability and disambiguation.
|
||||
@ -1149,7 +1174,7 @@ The special value `version :latest` is used when:
|
||||
* `url` does not contain any version information and there is no way to retrieve the version using a `livecheck`, or
|
||||
* having a correct value for `version` is too difficult or impractical, even with our automated systems. For example, [chromium.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/c/chromium.rb#L4) which releases multiple versions per day.
|
||||
|
||||
In both cases, using the special value [`sha256 :no_check`](#special-value-no_check) is also required.
|
||||
In both cases, using the special value [`sha256 :no_check`](#special-value-no_check) is also required. Casks that use `version :latest` are excluded from [autobump list](Autobump.md).
|
||||
|
||||
### Stanza: `zap`
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
last_review_date: "1970-01-01"
|
||||
last_review_date: "2025-06-16"
|
||||
---
|
||||
|
||||
# Formula Cookbook
|
||||
@ -746,6 +746,44 @@ end
|
||||
|
||||
For `url`/`regex` guidelines and additional `livecheck` block examples, refer to the [`brew livecheck` documentation](Brew-Livecheck.md). For more technical information on the methods used in a `livecheck` block, please refer to the [`Livecheck` class documentation](https://rubydoc.brew.sh/Livecheck).
|
||||
|
||||
### Excluding formula from autobump list
|
||||
|
||||
By default, all new formulae in the Homebrew/core repository are added to the autobump list. It means that future updates will be handled automatically by Homebrew CI jobs, and contributors do not have to do it manually.
|
||||
|
||||
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:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
To use this method, a reason must be provided. The preferred way is to use one of the available symbols:
|
||||
|
||||
* `:incompatible_version_format`: This reason is used when the `brew bump` command cannot determine a version for the URL or update it.
|
||||
* `:bumped_by_upstream`: Some developers whose programs are available in Homebrew want to take care of the updates themselves or even set up a CI action that does this. This `no_autobump!` reason exists for such cases.
|
||||
* `:requires_manual_review`: This is a temporary reason and expected to be deprecated in the future. It indicates that this package was not in the `autobump.txt` file before the new autobump list was introduced.
|
||||
|
||||
```ruby
|
||||
no_autobump! because: :incompatible_version_format
|
||||
```
|
||||
|
||||
The full list of available symbols is stored in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant) constant. 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.
|
||||
|
||||
### Unstable versions (`head`)
|
||||
|
||||
Formulae can specify an alternate download for the upstream project’s development cutting-edge source (e.g. `master`/`main`/`trunk`) using [`head`](https://rubydoc.brew.sh/Formula#head-class_method), which can be activated by passing `--HEAD` when installing. Specifying it is done in the same manner as [`url`](https://rubydoc.brew.sh/Formula#url-class_method):
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
last_review_date: "2025-02-08"
|
||||
last_review_date: "2025-06-16"
|
||||
---
|
||||
|
||||
# Documentation
|
||||
@ -52,6 +52,7 @@ last_review_date: "2025-02-08"
|
||||
- [Node for Formula Authors](Node-for-Formula-Authors.md)
|
||||
- [Python for Formula Authors](Python-for-Formula-Authors.md)
|
||||
- [`brew livecheck`](Brew-Livecheck.md)
|
||||
- [Autobump](Autobump.md)
|
||||
- [Migrating a Formula to a Tap](Migrating-A-Formula-To-A-Tap.md)
|
||||
- [Renaming a Formula](Rename-A-Formula.md)
|
||||
- [Building Against Non-Homebrew Dependencies](Building-Against-Non-Homebrew-Dependencies.md)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user