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

GithubRelease: Rework documentation comments

Browse Source 
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.
This commit is contained in:
Sam Ford 2023-05-15 23:34:43 -04:00
parent 1dd7556c74
commit a29b5c34d2
No known key found for this signature in database
GPG Key ID: 7AF5CBEE1DD6F76D
1 changed files with 21 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
Library/Homebrew/livecheck/strategy/github_release.rb
View File

@ -5,7 +5,8 @@ module Homebrew
module Livecheck module Livecheck
module Strategy module Strategy
# The {GithubRelease} strategy identifies versions of software at # 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: # 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/example/example/archive/v1.2.3.tar.gz`
# * `https://github.com/downloads/example/example/example-1.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 # {GithubRelease} should only be used when the upstream repository has
# has releases and the tagged release is appropriate to use # releases for suitable versions and the strategy is necessary or
# The strategy can only be applied by using `strategy :github_latest` # 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. # in a `livecheck` block.
# #
# The default regex identifies versions like `1.2.3`/`v1.2.3` in the name or tag. # The default regex identifies versions like `1.2.3`/`v1.2.3` in each
# This is a common tag format but a modified regex can be provided in a `livecheck` # release's tag or title. This is a common tag format but a modified
# block to override the default if a repository uses a different format (e.g. # regex can be provided in a `livecheck` block to override the default
# `example-1.2.3`, `1.2.3d`, `1.2.3-4`, etc.). # if a repository uses a different format (e.g. `1.2.3d`, `1.2.3-4`,
# etc.).
# #
# @api public # @api public
class GithubRelease class GithubRelease
@ -43,7 +47,9 @@ module Homebrew
# isn't provided. # isn't provided.
DEFAULT_REGEX = /v?(\d+(?:\.\d+)+)/i.freeze 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 VERSION_KEYS = ["tag_name", "name"].freeze
# Whether the strategy can be applied to the provided URL. # Whether the strategy can be applied to the provided URL.
@ -55,12 +61,13 @@ module Homebrew
URL_MATCH_REGEX.match?(url) URL_MATCH_REGEX.match?(url)
end 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 # provided, passes the JSON to the block to handle matching. With
# either approach, an array of unique matches is returned. # either approach, an array of unique matches is returned.
# #
# @param content [Array, Hash] list of releases or a single release # @param content [Array, Hash] array of releases or a single release
# @param regex [Regexp] a regex used for matching versions in the content # @param regex [Regexp] a regex used for matching versions in the
# content
# @param block [Proc, nil] a block to match the content # @param block [Proc, nil] a block to match the content
# @return [Array] # @return [Array]
sig { sig {
@ -95,8 +102,8 @@ module Homebrew
end.compact.uniq end.compact.uniq
end end
# Generates a URL and regex (if one isn't provided) and passes them # Generates the GitHub API URL for the repository's recent releases
# to {PageMatch.find_versions} to identify versions in the content. # and identifies versions from the JSON response.
# #
# @param url [String] the URL of the content to check # @param url [String] the URL of the content to check
# @param regex [Regexp] a regex used for matching versions in content # @param regex [Regexp] a regex used for matching versions in content