From 5139b9b468e60e4504d2ce52d8967147541f6c7b Mon Sep 17 00:00:00 2001
From: Sean Molenaar <smillerdev@me.com>
Date: Tue, 18 Apr 2023 15:42:26 +0200
Subject: [PATCH 01/12] feat: add github_release strategy

---
 Library/Homebrew/.rubocop.yml                 |   1 +
 Library/Homebrew/livecheck/strategy.rb        |   1 +
 .../livecheck/strategy/github_latest.rb       |  64 +--------
 .../livecheck/strategy/github_release.rb      | 130 ++++++++++++++++++
 4 files changed, 136 insertions(+), 60 deletions(-)
 create mode 100644 Library/Homebrew/livecheck/strategy/github_release.rb

diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
index 7c0b5f7255..303197f1ce 100644
--- a/Library/Homebrew/.rubocop.yml
+++ b/Library/Homebrew/.rubocop.yml
@@ -43,6 +43,7 @@ Style/Documentation:
     - livecheck/strategy/extract_plist.rb
     - livecheck/strategy/git.rb
     - livecheck/strategy/github_latest.rb
+    - livecheck/strategy/github_release.rb
     - livecheck/strategy/gnome.rb
     - livecheck/strategy/gnu.rb
     - livecheck/strategy/hackage.rb
diff --git a/Library/Homebrew/livecheck/strategy.rb b/Library/Homebrew/livecheck/strategy.rb
index 6cee9ded13..17bbcb27cc 100644
--- a/Library/Homebrew/livecheck/strategy.rb
+++ b/Library/Homebrew/livecheck/strategy.rb
@@ -270,6 +270,7 @@ require_relative "strategy/electron_builder"
 require_relative "strategy/extract_plist"
 require_relative "strategy/git"
 require_relative "strategy/github_latest"
+require_relative "strategy/github_release"
 require_relative "strategy/gnome"
 require_relative "strategy/gnu"
 require_relative "strategy/hackage"
diff --git a/Library/Homebrew/livecheck/strategy/github_latest.rb b/Library/Homebrew/livecheck/strategy/github_latest.rb
index 92792059b3..7caa270c06 100644
--- a/Library/Homebrew/livecheck/strategy/github_latest.rb
+++ b/Library/Homebrew/livecheck/strategy/github_latest.rb
@@ -34,28 +34,13 @@ module Homebrew
         # `strategy :github_latest` in a `livecheck` block.
         PRIORITY = 0
 
-        # The `Regexp` used to determine if the strategy applies to the URL.
-        URL_MATCH_REGEX = %r{
-          ^https?://github\.com
-          /(?:downloads/)?(?<username>[^/]+) # The GitHub username
-          /(?<repository>[^/]+)              # The GitHub repository name
-        }ix.freeze
-
-        # The default regex used to identify a version from a tag when a regex
-        # isn't provided.
-        DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze
-
-        # Keys in the release JSON that could contain the version.
-        # Tag name first since that is closer to other livechecks.
-        VERSION_KEYS = ["tag_name", "name"].freeze
-
         # Whether the strategy can be applied to the provided URL.
         #
         # @param url [String] the URL to match against
         # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
-          URL_MATCH_REGEX.match?(url)
+          GitHubRelease.match?(url)
         end
 
         # Extracts information from a provided URL and uses it to generate
@@ -69,7 +54,7 @@ module Homebrew
         def self.generate_input_values(url)
           values = {}
 
-          match = url.sub(/\.git$/i, "").match(URL_MATCH_REGEX)
+          match = url.delete_suffix(".git").match(GitHubRelease::URL_MATCH_REGEX)
           return values if match.blank?
 
           values[:url] = "https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases/latest"
@@ -79,46 +64,6 @@ module Homebrew
           values
         end
 
-        # Uses a regex to match the version from release JSON or, if a block is
-        # provided, passes the JSON to the block to handle matching. With
-        # either approach, an array of unique matches is returned.
-        #
-        # @param content [Array, Hash] list of releases or a single release
-        # @param regex [Regexp] a regex used for matching versions in the content
-        # @param block [Proc, nil] a block to match the content
-        # @return [Array]
-        sig {
-          params(
-            content: T.any(T::Array[T::Hash[String, T.untyped]], T::Hash[String, T.untyped]),
-            regex:   Regexp,
-            block:   T.nilable(Proc),
-          ).returns(T::Array[String])
-        }
-        def self.versions_from_content(content, regex, &block)
-          if block.present?
-            block_return_value = if regex.present?
-              yield(content, regex)
-            else
-              yield(content)
-            end
-            return Strategy.handle_block_return(block_return_value)
-          end
-
-          content = [content] unless content.is_a?(Array)
-          content.reject(&:blank?).map do |release|
-            next if release["draft"] || release["prerelease"]
-
-            value = T.let(nil, T.untyped)
-            VERSION_KEYS.find do |key|
-              match = release[key]&.match(regex)
-              next if match.blank?
-
-              value = match[1]
-            end
-            value
-          end.compact.uniq
-        end
-
         # Generates the GitHub API URL for the repository's "latest" release
         # and identifies the version from the JSON response.
         #
@@ -133,16 +78,15 @@ module Homebrew
             block:   T.nilable(Proc),
           ).returns(T::Hash[Symbol, T.untyped])
         }
-        def self.find_versions(url:, regex: DEFAULT_REGEX, **_unused, &block)
+        def self.find_versions(url:, regex: GitHubRelease::DEFAULT_REGEX, **_unused, &block)
           match_data = { matches: {}, regex: regex, url: url }
-
           generated = generate_input_values(url)
           return match_data if generated.blank?
 
           match_data[:url] = generated[:url]
 
           release = GitHub.get_latest_release(generated[:username], generated[:repository])
-          versions_from_content(release, regex, &block).each do |match_text|
+          GitHubRelease.versions_from_content(release, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end
 
diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
new file mode 100644
index 0000000000..7525b75018
--- /dev/null
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -0,0 +1,130 @@
+# typed: true
+# frozen_string_literal: true
+
+module Homebrew
+  module Livecheck
+    module Strategy
+      # The {GithubRelease} strategy identifies versions of software at
+      # github.com by checking a repository's release page.
+      #
+      # GitHub URLs take a few different formats:
+      #
+      # * `https://github.com/example/example/releases/download/1.2.3/example-1.2.3.tar.gz`
+      # * `https://github.com/example/example/archive/v1.2.3.tar.gz`
+      # * `https://github.com/downloads/example/example/example-1.2.3.tar.gz`
+      #
+      # This strategy should only be used when we know the upstream repository
+      # has releases and the tagged release is appropriate to use
+      # The strategy can only be applied by using `strategy :github_latest`
+      # in a `livecheck` block.
+      #
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the name or tag.
+      # This is a common tag format but a modified regex can be provided in a `livecheck`
+      # block to override the default if a repository uses a different format (e.g.
+      # `example-1.2.3`, `1.2.3d`, `1.2.3-4`, etc.).
+      #
+      # @api public
+      class GithubRelease
+        NICE_NAME = "GitHub - Releases"
+
+        # A priority of zero causes livecheck to skip the strategy. We do this
+        # for {GithubRelease} so we can selectively apply the strategy using
+        # `strategy :github_release` in a `livecheck` block.
+        PRIORITY = 0
+
+        # The `Regexp` used to determine if the strategy applies to the URL.
+        URL_MATCH_REGEX = %r{
+          ^https?://github\.com
+          /(?:downloads/)?(?<username>[^/]+) # The GitHub username
+          /(?<repository>[^/]+)              # The GitHub repository name
+        }ix.freeze
+
+        # The default regex used to identify a version from a tag when a regex
+        # isn't provided.
+        DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze
+
+        # Keys in the JSON that could contain the version.
+        VERSION_KEYS = ["tag_name", "name"].freeze
+
+        # Whether the strategy can be applied to the provided URL.
+        #
+        # @param url [String] the URL to match against
+        # @return [Boolean]
+        sig { params(url: String).returns(T::Boolean) }
+        def self.match?(url)
+          URL_MATCH_REGEX.match?(url)
+        end
+
+        # Uses a regex to match the version from release JSON or, if a block is
+        # provided, passes the JSON to the block to handle matching. With
+        # either approach, an array of unique matches is returned.
+        #
+        # @param content [Array, Hash] list of releases or a single release
+        # @param regex [Regexp] a regex used for matching versions in the content
+        # @param block [Proc, nil] a block to match the content
+        # @return [Array]
+        sig {
+          params(
+            content: T.any(T::Array[T::Hash[String, T.untyped]], T::Hash[String, T.untyped]),
+            regex:   Regexp,
+            block:   T.nilable(Proc),
+          ).returns(T::Array[String])
+        }
+        def self.versions_from_content(content, regex, &block)
+          if block.present?
+            block_return_value = if regex.present?
+              yield(content, regex)
+            else
+              yield(content)
+            end
+            return Strategy.handle_block_return(block_return_value)
+          end
+
+          content = [content] unless content.is_a?(Array)
+          content.reject(&:blank?).map do |release|
+            next if release["draft"] || release["prerelease"]
+
+            value = T.let(nil, T.untyped)
+            VERSION_KEYS.find do |key|
+              match = release[key]&.match(regex)
+              next if match.blank?
+
+              value = match[1]
+            end
+            value
+          end.compact.uniq
+        end
+
+        # Generates a URL and regex (if one isn't provided) and passes them
+        # to {PageMatch.find_versions} to identify versions in the content.
+        #
+        # @param url [String] the URL of the content to check
+        # @param regex [Regexp] a regex used for matching versions in content
+        # @return [Hash]
+        sig {
+          params(
+            url:     String,
+            regex:   T.nilable(Regexp),
+            _unused: T.nilable(T::Hash[Symbol, T.untyped]),
+            block:   T.nilable(Proc),
+          ).returns(T::Hash[Symbol, T.untyped])
+        }
+        def self.find_versions(url:, regex: GithubRelease::DEFAULT_REGEX, **_unused, &block)
+          match_data = { matches: {}, regex: regex }
+          match = url.delete_suffix(".git")
+                     .match(URL_MATCH_REGEX)
+          return match_data if match.blank?
+
+          releases = GitHub::API.open_rest("https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases")
+
+          GithubRelease.versions_from_content(releases, regex, &block).each do |match_text|
+            match_data[:matches][match_text] = Version.new(match_text)
+          end
+
+          match_data
+        end
+      end
+    end
+    GitHubRelease = Homebrew::Livecheck::Strategy::GithubRelease
+  end
+end

From db7a6baa33b0903963fe76be9f0ca6054ddf6f5a Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:28:43 -0400
Subject: [PATCH 02/12] GithubLatest: Fix test for GithubRelease changes

`GithubLatest` was updated to use parts of `GithubRelease` and this
works fine within `brew livecheck` (since we `require` all the
strategies) but we need to explicitly `require` `GithubRelease` in
the `GithubLatest` test file now. Without this, we encounter errors
in parts of `GithubLatest` where `GithubRelease` is referenced.
---
 Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb b/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
index 194463da91..1fc402d17c 100644
--- a/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "livecheck/strategy/github_release"
 require "livecheck/strategy/github_latest"
 
 describe Homebrew::Livecheck::Strategy::GithubLatest do

From 1dd7556c744dffac3faa56c146ae02b7d76a32fe Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:31:48 -0400
Subject: [PATCH 03/12] GithubLatest: Tweak documentation comments

---
 .../Homebrew/livecheck/strategy/github_latest.rb  | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_latest.rb b/Library/Homebrew/livecheck/strategy/github_latest.rb
index 7caa270c06..4534e1322c 100644
--- a/Library/Homebrew/livecheck/strategy/github_latest.rb
+++ b/Library/Homebrew/livecheck/strategy/github_latest.rb
@@ -16,14 +16,15 @@ module Homebrew
       #
       # {GithubLatest} should only be used when the upstream repository has a
       # "latest" release for a suitable version and the strategy is necessary
-      # or appropriate (e.g. {Git} returns an unreleased version or the
-      # `stable` URL is a release asset). The strategy can only be applied by
-      # using `strategy :github_latest` in a `livecheck` block.
+      # or appropriate (e.g. the formula/cask uses a release asset or the
+      # {Git} strategy returns an unreleased version). The strategy can only
+      # be applied by using `strategy :github_latest` in a `livecheck` block.
       #
-      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the
-      # release's tag name. This is a common tag format but a modified regex
-      # can be provided in a `livecheck` block to override the default if a
-      # repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`, etc.).
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in a
+      # release's tag or title. This is a common tag format but a modified
+      # regex can be provided in a `livecheck` block to override the default
+      # if a repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`,
+      # etc.).
       #
       # @api public
       class GithubLatest

From a29b5c34d20c062833d2c534b40eab19a1103e43 Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:34:43 -0400
Subject: [PATCH 04/12] GithubRelease: Rework documentation comments

The initial documentation comments contained some remaining text
referring to `GithubLatest` and hadn't been updated to incorporate
the recent changes to the aforementioned strategy. This also reworks
some of the language to better explain the strategy's function,
application, etc.
---
 .../livecheck/strategy/github_release.rb      | 35 +++++++++++--------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index 7525b75018..76629a0579 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -5,7 +5,8 @@ module Homebrew
   module Livecheck
     module Strategy
       # The {GithubRelease} strategy identifies versions of software at
-      # github.com by checking a repository's release page.
+      # github.com by checking a repository's recent releases using the
+      # GitHub API.
       #
       # GitHub URLs take a few different formats:
       #
@@ -13,15 +14,18 @@ module Homebrew
       # * `https://github.com/example/example/archive/v1.2.3.tar.gz`
       # * `https://github.com/downloads/example/example/example-1.2.3.tar.gz`
       #
-      # This strategy should only be used when we know the upstream repository
-      # has releases and the tagged release is appropriate to use
-      # The strategy can only be applied by using `strategy :github_latest`
+      # {GithubRelease} should only be used when the upstream repository has
+      # releases for suitable versions and the strategy is necessary or
+      # appropriate (e.g. the formula/cask uses a release asset and the
+      # {GithubLatest} strategy isn't sufficient to identify the newest version.
+      # The strategy can only be applied by using `strategy :github_release`
       # in a `livecheck` block.
       #
-      # The default regex identifies versions like `1.2.3`/`v1.2.3` in the name or tag.
-      # This is a common tag format but a modified regex can be provided in a `livecheck`
-      # block to override the default if a repository uses a different format (e.g.
-      # `example-1.2.3`, `1.2.3d`, `1.2.3-4`, etc.).
+      # The default regex identifies versions like `1.2.3`/`v1.2.3` in each
+      # release's tag or title. This is a common tag format but a modified
+      # regex can be provided in a `livecheck` block to override the default
+      # if a repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`,
+      # etc.).
       #
       # @api public
       class GithubRelease
@@ -43,7 +47,9 @@ module Homebrew
         # isn't provided.
         DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze
 
-        # Keys in the JSON that could contain the version.
+        # Keys in the release JSON that could contain the version.
+        # The tag name is checked first, to better align with the {Git}
+        # strategy.
         VERSION_KEYS = ["tag_name", "name"].freeze
 
         # Whether the strategy can be applied to the provided URL.
@@ -55,12 +61,13 @@ module Homebrew
           URL_MATCH_REGEX.match?(url)
         end
 
-        # Uses a regex to match the version from release JSON or, if a block is
+        # Uses a regex to match versions from release JSON or, if a block is
         # provided, passes the JSON to the block to handle matching. With
         # either approach, an array of unique matches is returned.
         #
-        # @param content [Array, Hash] list of releases or a single release
-        # @param regex [Regexp] a regex used for matching versions in the content
+        # @param content [Array, Hash] array of releases or a single release
+        # @param regex [Regexp] a regex used for matching versions in the
+        # content
         # @param block [Proc, nil] a block to match the content
         # @return [Array]
         sig {
@@ -95,8 +102,8 @@ module Homebrew
           end.compact.uniq
         end
 
-        # Generates a URL and regex (if one isn't provided) and passes them
-        # to {PageMatch.find_versions} to identify versions in the content.
+        # Generates the GitHub API URL for the repository's recent releases
+        # and identifies versions from the JSON response.
         #
         # @param url [String] the URL of the content to check
         # @param regex [Regexp] a regex used for matching versions in content

From 8a0f63e7286791fee769c44aa6267379385645ba Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:39:55 -0400
Subject: [PATCH 05/12] GithubRelease: Omit unnecessary prefix

---
 Library/Homebrew/livecheck/strategy/github_release.rb | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index 76629a0579..15d6112210 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -116,15 +116,14 @@ module Homebrew
             block:   T.nilable(Proc),
           ).returns(T::Hash[Symbol, T.untyped])
         }
-        def self.find_versions(url:, regex: GithubRelease::DEFAULT_REGEX, **_unused, &block)
+        def self.find_versions(url:, regex: DEFAULT_REGEX, **_unused, &block)
           match_data = { matches: {}, regex: regex }
           match = url.delete_suffix(".git")
                      .match(URL_MATCH_REGEX)
           return match_data if match.blank?
 
           releases = GitHub::API.open_rest("https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases")
-
-          GithubRelease.versions_from_content(releases, regex, &block).each do |match_text|
+          versions_from_content(releases, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end
 

From 701f7c5051bb8c2f4a61f2eccb63791b52dbde07 Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:40:28 -0400
Subject: [PATCH 06/12] GithubRelease: Update type signature

---
 Library/Homebrew/livecheck/strategy/github_release.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index 15d6112210..1efd34a756 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -111,7 +111,7 @@ module Homebrew
         sig {
           params(
             url:     String,
-            regex:   T.nilable(Regexp),
+            regex:   Regexp,
             _unused: T.nilable(T::Hash[Symbol, T.untyped]),
             block:   T.nilable(Proc),
           ).returns(T::Hash[Symbol, T.untyped])

From 263f486806e866547ec9e87c21ebd63c575a234e Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Mon, 15 May 2023 23:43:28 -0400
Subject: [PATCH 07/12] GithubRelease: Add #generate_input_values method

Keeping the logic for generating the API URL in a method makes it
testable, aligns with other strategies, and will help to enable some
future work.
---
 .../livecheck/strategy/github_latest.rb       |  1 +
 .../livecheck/strategy/github_release.rb      | 33 ++++++++++++++++---
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_latest.rb b/Library/Homebrew/livecheck/strategy/github_latest.rb
index 4534e1322c..e315c651a8 100644
--- a/Library/Homebrew/livecheck/strategy/github_latest.rb
+++ b/Library/Homebrew/livecheck/strategy/github_latest.rb
@@ -81,6 +81,7 @@ module Homebrew
         }
         def self.find_versions(url:, regex: GitHubRelease::DEFAULT_REGEX, **_unused, &block)
           match_data = { matches: {}, regex: regex, url: url }
+
           generated = generate_input_values(url)
           return match_data if generated.blank?
 
diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index 1efd34a756..cbd5a9a8a9 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -61,6 +61,27 @@ module Homebrew
           URL_MATCH_REGEX.match?(url)
         end
 
+        # Extracts information from a provided URL and uses it to generate
+        # various input values used by the strategy to check for new versions.
+        # Some of these values act as defaults and can be overridden in a
+        # `livecheck` block.
+        #
+        # @param url [String] the URL used to generate values
+        # @return [Hash]
+        sig { params(url: String).returns(T::Hash[Symbol, T.untyped]) }
+        def self.generate_input_values(url)
+          values = {}
+
+          match = url.delete_suffix(".git").match(URL_MATCH_REGEX)
+          return values if match.blank?
+
+          values[:url] = "#{GitHub::API_URL}/repos/#{match[:username]}/#{match[:repository]}/releases"
+          values[:username] = match[:username]
+          values[:repository] = match[:repository]
+
+          values
+        end
+
         # Uses a regex to match versions from release JSON or, if a block is
         # provided, passes the JSON to the block to handle matching. With
         # either approach, an array of unique matches is returned.
@@ -117,12 +138,14 @@ module Homebrew
           ).returns(T::Hash[Symbol, T.untyped])
         }
         def self.find_versions(url:, regex: DEFAULT_REGEX, **_unused, &block)
-          match_data = { matches: {}, regex: regex }
-          match = url.delete_suffix(".git")
-                     .match(URL_MATCH_REGEX)
-          return match_data if match.blank?
+          match_data = { matches: {}, regex: regex, url: url }
 
-          releases = GitHub::API.open_rest("https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases")
+          generated = generate_input_values(url)
+          return match_data if generated.blank?
+
+          match_data[:url] = generated[:url]
+
+          releases = GitHub::API.open_rest(generated[:url])
           versions_from_content(releases, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end

From a2fb2b00fd6bd5e81b0e9b03b7591144c8f72116 Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Tue, 16 May 2023 00:34:32 -0400
Subject: [PATCH 08/12] GithubRelease: Simplify block handling

The `#versions_from_content` method requires a regex and this will be
enforced by the type signature, so we don't have to check for the
presence of a regex when handling a `strategy` block.
---
 Library/Homebrew/livecheck/strategy/github_release.rb | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index cbd5a9a8a9..dcf09194c1 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -100,11 +100,7 @@ module Homebrew
         }
         def self.versions_from_content(content, regex, &block)
           if block.present?
-            block_return_value = if regex.present?
-              yield(content, regex)
-            else
-              yield(content)
-            end
+            block_return_value = yield(content, regex)
             return Strategy.handle_block_return(block_return_value)
           end
 

From bed4737826240faa8a8ed1ecf6d080f1deaf1664 Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Tue, 16 May 2023 00:36:36 -0400
Subject: [PATCH 09/12] GithubRelease: Add tests

This adds tests to cover all of the strategy outside of the
`#find_versions` method, which we don't currently test because it
involves a network request.
---
 .../livecheck/strategy/github_release_spec.rb | 157 ++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 Library/Homebrew/test/livecheck/strategy/github_release_spec.rb

diff --git a/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb b/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
new file mode 100644
index 0000000000..7c6948501e
--- /dev/null
+++ b/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "livecheck/strategy"
+
+describe Homebrew::Livecheck::Strategy::GithubRelease do
+  subject(:github_release) { described_class }
+
+  let(:github_urls) do
+    {
+      release_artifact:  "https://github.com/abc/def/releases/download/1.2.3/ghi-1.2.3.tar.gz",
+      tag_archive:       "https://github.com/abc/def/archive/v1.2.3.tar.gz",
+      repository_upload: "https://github.com/downloads/abc/def/ghi-1.2.3.tar.gz",
+    }
+  end
+  let(:non_github_url) { "https://brew.sh/test" }
+
+  let(:regex) { github_release::DEFAULT_REGEX }
+
+  let(:generated) do
+    {
+      url:        "https://api.github.com/repos/abc/def/releases",
+      username:   "abc",
+      repository: "def",
+    }
+  end
+
+  # For the sake of brevity, this is a limited subset of the information found
+  # in release objects in a response from the GitHub API. Some of these objects
+  # are somewhat representative of real world scenarios but others are
+  # contrived examples for the sake of exercising code paths.
+  let(:content) do
+    <<~EOS
+      [
+        {
+          "tag_name": "v1.2.3",
+          "name": "v1.2.3",
+          "draft": false,
+          "prerelease": false
+        },
+        {
+          "tag_name": "no-version-tag-also",
+          "name": "1.2.2",
+          "draft": false,
+          "prerelease": false
+        },
+        {
+          "tag_name": "1.2.1",
+          "name": "No version title",
+          "draft": false,
+          "prerelease": false
+        },
+        {
+          "tag_name": "no-version-tag",
+          "name": "No version title",
+          "draft": false,
+          "prerelease": false
+        },
+        {
+          "tag_name": "v1.1.2",
+          "name": "v1.1.2",
+          "draft": false,
+          "prerelease": true
+        },
+        {
+          "tag_name": "v1.1.1",
+          "name": "v1.1.1",
+          "draft": true,
+          "prerelease": false
+        },
+        {
+          "tag_name": "v1.1.0",
+          "name": "v1.1.0",
+          "draft": true,
+          "prerelease": true
+        },
+        {
+          "other": "something-else"
+        }
+      ]
+    EOS
+  end
+  let(:json) { JSON.parse(content) }
+
+  let(:matches) { ["1.2.3", "1.2.2", "1.2.1"] }
+
+  describe "::match?" do
+    it "returns true for a GitHub release artifact URL" do
+      expect(github_release.match?(github_urls[:release_artifact])).to be true
+    end
+
+    it "returns true for a GitHub tag archive URL" do
+      expect(github_release.match?(github_urls[:tag_archive])).to be true
+    end
+
+    it "returns true for a GitHub repository upload URL" do
+      expect(github_release.match?(github_urls[:repository_upload])).to be true
+    end
+
+    it "returns false for a non-GitHub URL" do
+      expect(github_release.match?(non_github_url)).to be false
+    end
+  end
+
+  describe "::generate_input_values" do
+    it "returns a hash containing a url and regex for a GitHub release artifact URL" do
+      expect(github_release.generate_input_values(github_urls[:release_artifact])).to eq(generated)
+    end
+
+    it "returns a hash containing a url and regex for a GitHub tag archive URL" do
+      expect(github_release.generate_input_values(github_urls[:tag_archive])).to eq(generated)
+    end
+
+    it "returns a hash containing a url and regex for a GitHub repository upload URL" do
+      expect(github_release.generate_input_values(github_urls[:repository_upload])).to eq(generated)
+    end
+
+    it "returns an empty hash for a non-Github URL" do
+      expect(github_release.generate_input_values(non_github_url)).to eq({})
+    end
+  end
+
+  describe "::versions_from_content" do
+    it "returns an empty array if content is blank" do
+      expect(github_release.versions_from_content({}, regex)).to eq([])
+    end
+
+    it "returns an array of version strings when given content" do
+      expect(github_release.versions_from_content(json, regex)).to eq(matches)
+    end
+
+    it "returns an array of version strings when given content and a block" do
+      # Returning a string from block
+      expect(github_release.versions_from_content(json, regex) { "1.2.3" }).to eq(["1.2.3"])
+
+      # Returning an array of strings from block
+      expect(github_release.versions_from_content(json, regex) do |json, regex|
+        json.map do |release|
+          next if release["draft"] || release["prerelease"]
+
+          match = release["tag_name"]&.match(regex)
+          next if match.blank?
+
+          match[1]
+        end
+      end).to eq(["1.2.3", "1.2.1"])
+    end
+
+    it "allows a nil return from a block" do
+      expect(github_release.versions_from_content(json, regex) { next }).to eq([])
+    end
+
+    it "errors on an invalid return type from a block" do
+      expect { github_release.versions_from_content(json, regex) { 123 } }
+        .to raise_error(TypeError, Homebrew::Livecheck::Strategy::INVALID_BLOCK_RETURN_VALUE_MSG)
+    end
+  end
+end

From 940b63cad321f51ae69fef74082e3f6268b3c769 Mon Sep 17 00:00:00 2001
From: Sean Molenaar <smillerdev@me.com>
Date: Tue, 16 May 2023 19:51:20 +0200
Subject: [PATCH 10/12] chore: rename GitHubRelease to GitHubReleases

---
 Library/Homebrew/livecheck/strategy/github_latest.rb   |  8 ++++----
 Library/Homebrew/livecheck/strategy/github_release.rb  | 10 +++++-----
 .../test/livecheck/strategy/github_release_spec.rb     |  2 +-
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/Library/Homebrew/livecheck/strategy/github_latest.rb b/Library/Homebrew/livecheck/strategy/github_latest.rb
index e315c651a8..bd743645a6 100644
--- a/Library/Homebrew/livecheck/strategy/github_latest.rb
+++ b/Library/Homebrew/livecheck/strategy/github_latest.rb
@@ -41,7 +41,7 @@ module Homebrew
         # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
-          GitHubRelease.match?(url)
+          GitHubReleases.match?(url)
         end
 
         # Extracts information from a provided URL and uses it to generate
@@ -55,7 +55,7 @@ module Homebrew
         def self.generate_input_values(url)
           values = {}
 
-          match = url.delete_suffix(".git").match(GitHubRelease::URL_MATCH_REGEX)
+          match = url.delete_suffix(".git").match(GitHubReleases::URL_MATCH_REGEX)
           return values if match.blank?
 
           values[:url] = "https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases/latest"
@@ -79,7 +79,7 @@ module Homebrew
             block:   T.nilable(Proc),
           ).returns(T::Hash[Symbol, T.untyped])
         }
-        def self.find_versions(url:, regex: GitHubRelease::DEFAULT_REGEX, **_unused, &block)
+        def self.find_versions(url:, regex: GitHubReleases::DEFAULT_REGEX, **_unused, &block)
           match_data = { matches: {}, regex: regex, url: url }
 
           generated = generate_input_values(url)
@@ -88,7 +88,7 @@ module Homebrew
           match_data[:url] = generated[:url]
 
           release = GitHub.get_latest_release(generated[:username], generated[:repository])
-          GitHubRelease.versions_from_content(release, regex, &block).each do |match_text|
+          GitHubReleases.versions_from_content(release, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end
 
diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_release.rb
index dcf09194c1..2c69209680 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_release.rb
@@ -4,7 +4,7 @@
 module Homebrew
   module Livecheck
     module Strategy
-      # The {GithubRelease} strategy identifies versions of software at
+      # The {GithubReleases} strategy identifies versions of software at
       # github.com by checking a repository's recent releases using the
       # GitHub API.
       #
@@ -14,7 +14,7 @@ module Homebrew
       # * `https://github.com/example/example/archive/v1.2.3.tar.gz`
       # * `https://github.com/downloads/example/example/example-1.2.3.tar.gz`
       #
-      # {GithubRelease} should only be used when the upstream repository has
+      # {GithubReleases} should only be used when the upstream repository has
       # releases for suitable versions and the strategy is necessary or
       # appropriate (e.g. the formula/cask uses a release asset and the
       # {GithubLatest} strategy isn't sufficient to identify the newest version.
@@ -28,11 +28,11 @@ module Homebrew
       # etc.).
       #
       # @api public
-      class GithubRelease
+      class GithubReleases
         NICE_NAME = "GitHub - Releases"
 
         # A priority of zero causes livecheck to skip the strategy. We do this
-        # for {GithubRelease} so we can selectively apply the strategy using
+        # for {GithubReleases} so we can selectively apply the strategy using
         # `strategy :github_release` in a `livecheck` block.
         PRIORITY = 0
 
@@ -150,6 +150,6 @@ module Homebrew
         end
       end
     end
-    GitHubRelease = Homebrew::Livecheck::Strategy::GithubRelease
+    GitHubReleases = Homebrew::Livecheck::Strategy::GithubReleases
   end
 end
diff --git a/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb b/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
index 7c6948501e..0f6895b588 100644
--- a/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
@@ -2,7 +2,7 @@
 
 require "livecheck/strategy"
 
-describe Homebrew::Livecheck::Strategy::GithubRelease do
+describe Homebrew::Livecheck::Strategy::GitHubReleases do
   subject(:github_release) { described_class }
 
   let(:github_urls) do

From 104d30d23135036f21ae1be74a7698016ffa49ac Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Tue, 16 May 2023 14:22:10 -0400
Subject: [PATCH 11/12] Finish renaming GithubRelease to GithubReleases

---
 Library/Homebrew/.rubocop.yml                 |  2 +-
 Library/Homebrew/livecheck/strategy.rb        |  2 +-
 .../livecheck/strategy/github_latest.rb       |  8 ++---
 .../{github_release.rb => github_releases.rb} |  4 +--
 .../livecheck/strategy/github_latest_spec.rb  |  2 +-
 ...elease_spec.rb => github_releases_spec.rb} | 34 +++++++++----------
 6 files changed, 26 insertions(+), 26 deletions(-)
 rename Library/Homebrew/livecheck/strategy/{github_release.rb => github_releases.rb} (98%)
 rename Library/Homebrew/test/livecheck/strategy/{github_release_spec.rb => github_releases_spec.rb} (72%)

diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
index 303197f1ce..69df9b23f3 100644
--- a/Library/Homebrew/.rubocop.yml
+++ b/Library/Homebrew/.rubocop.yml
@@ -43,7 +43,7 @@ Style/Documentation:
     - livecheck/strategy/extract_plist.rb
     - livecheck/strategy/git.rb
     - livecheck/strategy/github_latest.rb
-    - livecheck/strategy/github_release.rb
+    - livecheck/strategy/github_releases.rb
     - livecheck/strategy/gnome.rb
     - livecheck/strategy/gnu.rb
     - livecheck/strategy/hackage.rb
diff --git a/Library/Homebrew/livecheck/strategy.rb b/Library/Homebrew/livecheck/strategy.rb
index 17bbcb27cc..6710700dcf 100644
--- a/Library/Homebrew/livecheck/strategy.rb
+++ b/Library/Homebrew/livecheck/strategy.rb
@@ -270,7 +270,7 @@ require_relative "strategy/electron_builder"
 require_relative "strategy/extract_plist"
 require_relative "strategy/git"
 require_relative "strategy/github_latest"
-require_relative "strategy/github_release"
+require_relative "strategy/github_releases"
 require_relative "strategy/gnome"
 require_relative "strategy/gnu"
 require_relative "strategy/hackage"
diff --git a/Library/Homebrew/livecheck/strategy/github_latest.rb b/Library/Homebrew/livecheck/strategy/github_latest.rb
index bd743645a6..9207c60cc6 100644
--- a/Library/Homebrew/livecheck/strategy/github_latest.rb
+++ b/Library/Homebrew/livecheck/strategy/github_latest.rb
@@ -41,7 +41,7 @@ module Homebrew
         # @return [Boolean]
         sig { params(url: String).returns(T::Boolean) }
         def self.match?(url)
-          GitHubReleases.match?(url)
+          GithubReleases.match?(url)
         end
 
         # Extracts information from a provided URL and uses it to generate
@@ -55,7 +55,7 @@ module Homebrew
         def self.generate_input_values(url)
           values = {}
 
-          match = url.delete_suffix(".git").match(GitHubReleases::URL_MATCH_REGEX)
+          match = url.delete_suffix(".git").match(GithubReleases::URL_MATCH_REGEX)
           return values if match.blank?
 
           values[:url] = "https://api.github.com/repos/#{match[:username]}/#{match[:repository]}/releases/latest"
@@ -79,7 +79,7 @@ module Homebrew
             block:   T.nilable(Proc),
           ).returns(T::Hash[Symbol, T.untyped])
         }
-        def self.find_versions(url:, regex: GitHubReleases::DEFAULT_REGEX, **_unused, &block)
+        def self.find_versions(url:, regex: GithubReleases::DEFAULT_REGEX, **_unused, &block)
           match_data = { matches: {}, regex: regex, url: url }
 
           generated = generate_input_values(url)
@@ -88,7 +88,7 @@ module Homebrew
           match_data[:url] = generated[:url]
 
           release = GitHub.get_latest_release(generated[:username], generated[:repository])
-          GitHubReleases.versions_from_content(release, regex, &block).each do |match_text|
+          GithubReleases.versions_from_content(release, regex, &block).each do |match_text|
             match_data[:matches][match_text] = Version.new(match_text)
           end
 
diff --git a/Library/Homebrew/livecheck/strategy/github_release.rb b/Library/Homebrew/livecheck/strategy/github_releases.rb
similarity index 98%
rename from Library/Homebrew/livecheck/strategy/github_release.rb
rename to Library/Homebrew/livecheck/strategy/github_releases.rb
index 2c69209680..eb18bdbe0f 100644
--- a/Library/Homebrew/livecheck/strategy/github_release.rb
+++ b/Library/Homebrew/livecheck/strategy/github_releases.rb
@@ -18,7 +18,7 @@ module Homebrew
       # releases for suitable versions and the strategy is necessary or
       # appropriate (e.g. the formula/cask uses a release asset and the
       # {GithubLatest} strategy isn't sufficient to identify the newest version.
-      # The strategy can only be applied by using `strategy :github_release`
+      # The strategy can only be applied by using `strategy :github_releases`
       # in a `livecheck` block.
       #
       # The default regex identifies versions like `1.2.3`/`v1.2.3` in each
@@ -33,7 +33,7 @@ module Homebrew
 
         # A priority of zero causes livecheck to skip the strategy. We do this
         # for {GithubReleases} so we can selectively apply the strategy using
-        # `strategy :github_release` in a `livecheck` block.
+        # `strategy :github_releases` in a `livecheck` block.
         PRIORITY = 0
 
         # The `Regexp` used to determine if the strategy applies to the URL.
diff --git a/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb b/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
index 1fc402d17c..f118e11407 100644
--- a/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/github_latest_spec.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "livecheck/strategy/github_release"
+require "livecheck/strategy/github_releases"
 require "livecheck/strategy/github_latest"
 
 describe Homebrew::Livecheck::Strategy::GithubLatest do
diff --git a/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb b/Library/Homebrew/test/livecheck/strategy/github_releases_spec.rb
similarity index 72%
rename from Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
rename to Library/Homebrew/test/livecheck/strategy/github_releases_spec.rb
index 0f6895b588..597472509f 100644
--- a/Library/Homebrew/test/livecheck/strategy/github_release_spec.rb
+++ b/Library/Homebrew/test/livecheck/strategy/github_releases_spec.rb
@@ -2,8 +2,8 @@
 
 require "livecheck/strategy"
 
-describe Homebrew::Livecheck::Strategy::GitHubReleases do
-  subject(:github_release) { described_class }
+describe Homebrew::Livecheck::Strategy::GithubReleases do
+  subject(:github_releases) { described_class }
 
   let(:github_urls) do
     {
@@ -14,7 +14,7 @@ describe Homebrew::Livecheck::Strategy::GitHubReleases do
   end
   let(:non_github_url) { "https://brew.sh/test" }
 
-  let(:regex) { github_release::DEFAULT_REGEX }
+  let(:regex) { github_releases::DEFAULT_REGEX }
 
   let(:generated) do
     {
@@ -85,55 +85,55 @@ describe Homebrew::Livecheck::Strategy::GitHubReleases do
 
   describe "::match?" do
     it "returns true for a GitHub release artifact URL" do
-      expect(github_release.match?(github_urls[:release_artifact])).to be true
+      expect(github_releases.match?(github_urls[:release_artifact])).to be true
     end
 
     it "returns true for a GitHub tag archive URL" do
-      expect(github_release.match?(github_urls[:tag_archive])).to be true
+      expect(github_releases.match?(github_urls[:tag_archive])).to be true
     end
 
     it "returns true for a GitHub repository upload URL" do
-      expect(github_release.match?(github_urls[:repository_upload])).to be true
+      expect(github_releases.match?(github_urls[:repository_upload])).to be true
     end
 
     it "returns false for a non-GitHub URL" do
-      expect(github_release.match?(non_github_url)).to be false
+      expect(github_releases.match?(non_github_url)).to be false
     end
   end
 
   describe "::generate_input_values" do
     it "returns a hash containing a url and regex for a GitHub release artifact URL" do
-      expect(github_release.generate_input_values(github_urls[:release_artifact])).to eq(generated)
+      expect(github_releases.generate_input_values(github_urls[:release_artifact])).to eq(generated)
     end
 
     it "returns a hash containing a url and regex for a GitHub tag archive URL" do
-      expect(github_release.generate_input_values(github_urls[:tag_archive])).to eq(generated)
+      expect(github_releases.generate_input_values(github_urls[:tag_archive])).to eq(generated)
     end
 
     it "returns a hash containing a url and regex for a GitHub repository upload URL" do
-      expect(github_release.generate_input_values(github_urls[:repository_upload])).to eq(generated)
+      expect(github_releases.generate_input_values(github_urls[:repository_upload])).to eq(generated)
     end
 
     it "returns an empty hash for a non-Github URL" do
-      expect(github_release.generate_input_values(non_github_url)).to eq({})
+      expect(github_releases.generate_input_values(non_github_url)).to eq({})
     end
   end
 
   describe "::versions_from_content" do
     it "returns an empty array if content is blank" do
-      expect(github_release.versions_from_content({}, regex)).to eq([])
+      expect(github_releases.versions_from_content({}, regex)).to eq([])
     end
 
     it "returns an array of version strings when given content" do
-      expect(github_release.versions_from_content(json, regex)).to eq(matches)
+      expect(github_releases.versions_from_content(json, regex)).to eq(matches)
     end
 
     it "returns an array of version strings when given content and a block" do
       # Returning a string from block
-      expect(github_release.versions_from_content(json, regex) { "1.2.3" }).to eq(["1.2.3"])
+      expect(github_releases.versions_from_content(json, regex) { "1.2.3" }).to eq(["1.2.3"])
 
       # Returning an array of strings from block
-      expect(github_release.versions_from_content(json, regex) do |json, regex|
+      expect(github_releases.versions_from_content(json, regex) do |json, regex|
         json.map do |release|
           next if release["draft"] || release["prerelease"]
 
@@ -146,11 +146,11 @@ describe Homebrew::Livecheck::Strategy::GitHubReleases do
     end
 
     it "allows a nil return from a block" do
-      expect(github_release.versions_from_content(json, regex) { next }).to eq([])
+      expect(github_releases.versions_from_content(json, regex) { next }).to eq([])
     end
 
     it "errors on an invalid return type from a block" do
-      expect { github_release.versions_from_content(json, regex) { 123 } }
+      expect { github_releases.versions_from_content(json, regex) { 123 } }
         .to raise_error(TypeError, Homebrew::Livecheck::Strategy::INVALID_BLOCK_RETURN_VALUE_MSG)
     end
   end

From 9b6e8f8dc52072f6b68d2e6de7f613ba9fbaa3f6 Mon Sep 17 00:00:00 2001
From: Sam Ford <1584702+samford@users.noreply.github.com>
Date: Tue, 16 May 2023 15:17:42 -0400
Subject: [PATCH 12/12] Update brew livecheck documentation

---
 docs/Brew-Livecheck.md | 48 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/docs/Brew-Livecheck.md b/docs/Brew-Livecheck.md
index 29a2f75ce5..bc6e89cd4c 100644
--- a/docs/Brew-Livecheck.md
+++ b/docs/Brew-Livecheck.md
@@ -27,7 +27,7 @@ This can be accomplished by adding a `livecheck` block to the formula/cask/resou
 
 * **Only use `strategy` when it's necessary**. For example, if livecheck is already using the `Git` strategy for a URL, it's not necessary to use `strategy :git`. However, if `Git` applies to a URL but we need to use `PageMatch`, it's necessary to specify `strategy :page_match`.
 
-* **Only use the `GithubLatest` strategy when it's necessary and correct**. GitHub rate-limits requests so we try to minimize our use of this strategy to avoid hitting the rate limit on CI or when using `brew livecheck --tap` on large taps (e.g. `homebrew/core`). The `Git` strategy is often sufficient and we only need to use `GithubLatest` when the "latest" release is different than the newest version from the tags.
+* **Only use the `GithubLatest` and `GithubReleases` strategies when they are necessary and correct**. GitHub rate limits API requests, so we only use these strategies when `Git` isn't sufficient or appropriate. `GithubLatest` should only be used if the upstream repository has a "latest" release for a suitable version and either the formula/cask uses a release asset or the `Git` strategy can't correctly identify the latest release version. `GithubReleases` should only be used if the upstream repository uses releases and both the `Git` and `GithubLatest` strategies aren't suitable.
 
 ### URL guidelines
 
@@ -141,6 +141,52 @@ livecheck do
 end
 ```
 
+#### `GithubLatest` `strategy` block
+
+A `strategy` block for `GithubLatest` receives the parsed JSON data from the GitHub API for a repository's "latest" release, along with a regex. When a regex is not provided in a `livecheck` block, the strategy's default regex is passed into the `strategy` block instead.
+
+By default, the strategy matches version text in the release's tag or title but a `strategy` block can be used to check any of the fields in the release JSON. The logic in the following `strategy` block is similar to the default behavior but only checks the release tag instead, for the sake of demonstration:
+
+```ruby
+livecheck do
+  url :stable
+  regex(/^example[._-]v?(\d+(?:\.\d+)+)$/i)
+  strategy :github_latest do |json, regex|
+    match = json["tag_name"]&.match(regex)
+    next if match.blank?
+
+    match[1]
+  end
+end
+```
+
+You can find more information on the response JSON from this API endpoint in the related [GitHub REST API documentation](https://docs.github.com/en/rest/releases/releases?apiVersion=latest#get-the-latest-release).
+
+#### `GithubReleases` `strategy` block
+
+A `strategy` block for `GithubReleases` receives the parsed JSON data from the GitHub API for a repository's most recent releases, along with a regex. When a regex is not provided in a `livecheck` block, the strategy's default regex is passed into the `strategy` block instead.
+
+By default, the strategy matches version text in each release's tag or title but a `strategy` block can be used to check any of the fields in the release JSON. The logic in the following `strategy` block is similar to the default behavior but only checks the release tag instead, for the sake of demonstration:
+
+```ruby
+livecheck do
+  url :stable
+  regex(/^example[._-]v?(\d+(?:\.\d+)+)$/i)
+  strategy :github_releases do |json, regex|
+    json.map do |release|
+      next if release["draft"] || release["prerelease"]
+
+      match = json["tag_name"]&.match(regex)
+      next if match.blank?
+
+      match[1]
+    end
+  end
+end
+```
+
+You can find more information on the response JSON from this API endpoint in the related [GitHub REST API documentation](https://docs.github.com/en/rest/releases/releases?apiVersion=latest#list-releases).
+
 #### `Json` `strategy` block
 
 A `strategy` block for `Json` receives parsed JSON data and, if provided, a regex. For example, if we have an object containing an array of objects with a `version` string, we can select only the members that match the regex and isolate the relevant version text as follows: