diff --git a/docs/Autobump.md b/docs/Autobump.md index 0330bc0acd..0beaf0bac0 100644 --- a/docs/Autobump.md +++ b/docs/Autobump.md @@ -4,28 +4,19 @@ 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. +[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. -## Excluding packages from autobump list +## 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 added to the list. To exclude a package from the list, it should satisfy one of the following: +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: -1. The package is deprecated or disabled. -2. The The Livecheck block has a `skip` method. -3. It has a `no_autobump!` method/stanza. +1. have a `deprecate!` or `disable!` call +2. have a `livecheck do` block containing a `skip` call +3. has no `no_autobump!` call -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. +There are other formula or cask-specific reasons listed in the Formula Cookbook and Cask Cookbook respectively. -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///foo--.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`. +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). The reasons can be specified by their symbols: @@ -33,10 +24,10 @@ The reasons can be specified by their symbols: no_autobump! because: :bumped_by_upstream ``` -If none of the reasons from above fit, a custom reason can be provided as a string: +If none of the existing reasons 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`. +If there are multiple packages with a similar custom reason, it be added to `NO_AUTOBUMP_REASONS_LIST`. diff --git a/docs/Brew-Livecheck.md b/docs/Brew-Livecheck.md index 6a12d5ca43..6f69c0c0c6 100644 --- a/docs/Brew-Livecheck.md +++ b/docs/Brew-Livecheck.md @@ -1,5 +1,5 @@ --- -last_review_date: 2025-06-23 +last_review_date: 2025-05-28 --- # `brew livecheck` @@ -438,7 +438,7 @@ livecheck do end ``` -Note that if a package uses this livecheck strategy it will be excluded from [autobump list](Autobump.md). +Note that if a package uses this livecheck strategy it will be excluded from [autobumping](Autobump.md) as this strategy has negative impact on CI time. ### `throttle` diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index 6b30058fbd..6e85c43071 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -1,5 +1,5 @@ --- -last_review_date: "2025-06-16" +last_review_date: 2025-05-18 --- # Cask Cookbook @@ -175,7 +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. | +| [`no_autobump!`](#stanza-no_autobump) | no | Allowed symbol or a string. Excludes cask from autobumping if set. | ## Stanza descriptions @@ -648,17 +648,13 @@ Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to writ 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. +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). ```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: +A custom reason can be provided if none of the available symbols fits: ```ruby no_autobump! because: "some unique reason" @@ -1174,7 +1170,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. Casks that use `version :latest` are excluded from [autobump list](Autobump.md). +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 [autobumping](Autobump.md). ### Stanza: `zap` diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 78f8f5c7bc..c101c67c59 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -1,5 +1,5 @@ --- -last_review_date: "2025-06-16" +last_review_date: "1970-01-01" --- # Formula Cookbook @@ -746,7 +746,7 @@ 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 +### Excluding formula from autobumping 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. @@ -766,17 +766,13 @@ class Foo < Formula 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. +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 ``` -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: +A custom reason can be provided if none of the available symbols fits: ```ruby no_autobump! because: "some unique reason" diff --git a/docs/index.md b/docs/index.md index 352931a5e9..58eaa29bd7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -last_review_date: "2025-06-16" +last_review_date: "2025-02-08" --- # Documentation