[bevanjkay]

• Brew-Livecheck.md allowed GithubLatest whenever a release asset was used, which covers nearly every GitHub-hosted cask.
• Git is inferred from GitHub URLs, needs no livecheck block and is much lighter than an API request, so say so and limit GithubLatest to tags without releases or unfilterable pre-releases.
• Add the same guidance to the Cask and Formula Cookbooks and the GithubLatest rubydoc.
• Replace the calibre example's github_latest with the cask's current header_match check so the cookbook doesn't model it.

This makes the docs align more closely with our prevailing standards.

---

• Have you followed our Contributing guidelines?
• Have you checked for other open Pull Requests for the same change?
• Have you explained what your changes do? Performance claims (e.g. "this is faster") must include brew benchmark results.
• Have you explained why you'd like these changes included, not just what they do?
• For bug fixes, have you given step-by-step brew commands to reproduce the bug?
• Have you written new tests (excluding integration tests)? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) locally?

---

• I did not use AI/LLM to create this PR, or I disclosed the tool/model below and reviewed its output; I did not attribute commits to AI and will answer maintainer questions and review comments myself without AI/LLM.

Claude with Opus 5.5 at High effort, with local review and testing.

---

Summary by CodeRabbit

• Documentation
  • Clarified that the GitHub “latest” strategy is suitable when Git cannot reliably identify the latest version, including cases with pre-release tags, tags without releases, or a notable gap between a tag and release. The “latest” release must identify the correct version.
  • Clarified that the GitHub releases strategy applies when a repository uses releases and neither Git nor the “latest” strategy is sufficient.
  • Updated livecheck guidance to omit a block when a strategy already provides correct version information without changes.
  • Updated Calibre’s livecheck to check its distribution URL instead of GitHub releases.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 77abb565-e2a7-417d-9095-aa286de8ecaf

📥 Commits

Reviewing files that changed from the base of the PR and between 0ed1a3f and 655b03d.

📒 Files selected for processing: 2

• docs/Brew-Livecheck.md
• docs/Cask-Cookbook.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The changes revise guidance for selecting GithubLatest and GithubReleases. The cookbooks explain when a livecheck block can be omitted. The Calibre example uses a distribution URL with :header_match.

Changes: Livecheck guidance

Layer / File(s)	Summary
Strategy selection guidance Library/Homebrew/livecheck/strategy/github_latest.rb, docs/Brew-Livecheck.md	The guidance describes when GithubLatest can identify the latest version and when to use GithubReleases.
Cookbook guidance docs/Formula-Cookbook.md, docs/Cask-Cookbook.md	The cookbooks state that a livecheck block can be omitted when its strategy returns correct version information without changes. The Calibre example uses the distribution URL and :header_match.

Priority: ➖ Normal

Merge Risk: 🔵 Low · up to 655b0

The documentation changes are low risk overall, but unresolved strategy guidance and formatting issues remain before merge.

Pre-merge checks: 4

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: preferring Git livecheck over GithubLatest in the updated guidance.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 21c9613a-8207-4219-a224-d8237a058ef3

📥 Commits

Reviewing files that changed from the base of the PR and between aac1fb8 and e13c48f.

📒 Files selected for processing: 4

• Library/Homebrew/livecheck/strategy/github_latest.rb
• docs/Brew-Livecheck.md
• docs/Cask-Cookbook.md
• docs/Formula-Cookbook.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[MikeMcQuaid]

Good idea! Looks good. Will hold merging until @samford weighs in.

[samford]

I ran out of time while reviewing this today but I'll finish it up tomorrow and send along comments/suggestions.

[samford]

I've added inline comments and suggestions but I would prefer a more limited approach here. This is just my perspective (and feel free to provide more commentary if you disagree) but hopefully this provides some additional context (for the past, present, and future).

The primary reason we use Git even when GithubLatest works is because Git doesn't contribute to GitHub API limits. It's not always lighter than GithubLatest (e.g., repositories with a ton of tags), so we shouldn't document that as a reason. A GitHub release is a stronger signal than a tag that a version is released, so GithubLatest has always been preferable in that respect but I limited its usage simply due to the rate limit. [Some repositories also make a mess of their releases, so the "latest" release isn't guaranteed to be reliable and the situation has to be researched before we apply GithubLatest.]

With that in mind, I'm not in favor of adding explicit language to say that we always prefer the Git strategy when a formula/cask uses a GitHub asset. livecheck automatically uses Git due to the strategy's priority, so contributors only need to know that they should avoid using GithubLatest/GithubReleases when those strategies aren't strictly necessary, which the existing documentation covers. There's also a reasonable chance that we will reverse course and allow the GithubLatest strategy to be used more freely after some technical improvements reduce its API rate limit usage.

I've mentioned this before (e.g., #21645) but I have an in-progress implementation of a livecheck feature that batches GithubLatest checks across a given brew livecheck run, which drastically reduces API requests. This allows livecheck to fetch the data for 100 GithubLatest checks in one request and if we also limit it to only the fields that we need (e.g., tag_name), that will be much more efficient in terms of time, data transfer, API rate limit, etc. With that change, GithubLatest would end up being a lighter approach than individual Git checks for compatible repositories when it comes to large runs.

From my testing, the batched approach works well for simple checks (matching the version from the tag name) but checks with a strategy block may be using parts of the API data other than the tag name, so those require a way of specifying what data is needed (e.g., as a strategy option) or we could simply standardize on a broader set of fields for checks with a strategy block (with an option for the full JSON if needed). [Granted, we can roll it out for simple checks first and add support for strategy blocks afterward.]

That said, this depends on some architectural changes inside of livecheck that I have to push out beforehand and that's tied in with work on caching support (which also has a sort of queueing component). This approach would benefit autobump (and --tap runs) but livecheck audits in CI runs would naturally contribute to the API rate limit, so I also need to look into improving the livecheck CI situation before we consider allowing GithubLatest to be used more broadly (e.g., some checks don't vary based on arch/OS but they're unnecessarily run multiple times due to being part of brew audit).

In the immediate term, I'm working on a PR to tweak the GithubLatest strategy to allow it to use a GraphQL request to only fetch the tag_name field when a strategy block isn't used. That leads to a reliably small response body (generally less than 100 bytes), whereas responses from the REST API vary in size and can typically be anywhere from a few KB to 100+ KB (the release body text can be quite lengthy). This approach produces the same version information and uses the same number of API requests for now but it would minimize data transfer in the interim time.

Long story short, there's still work to do but the end goal is to make GithubLatest much lighter (in terms of API requests and data transfer), so I intentionally left the Git preference somewhat implicit in the documentation. I think the existing language around GithubLatest/GithubReleases is mostly sufficient, so more limited/targeted changes would be better here.

[bevanjkay]

Thanks @samford, I've applied your suggestions and I generally agree with your thoughts. I'm not too concerned about the semantics here. The primary motivation was clearing up the case where contributors and AI agents would always reach for GithubLatest because the docs read as though it was the solution to most cases.

Two things I wanted to point to:

1. "Lighter" was the wrong word. What I meant is that Git doesn't use the GitHub API, and that's the major factor. Network and data transfer are less of an issue here in my opinion.

2. I don't think there's value in shaping the documentation around changes that were mentioned as being on the way over six months ago. If they land, we can update the docs then. The problem right now is that AI models are adding a GithubLatest livecheck almost every time because of how they interpret the current documentation. At this point, how an AI agent reads the docs matters more than how they read to us.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0089d936-9bd6-42eb-80d0-494085bfa78b

📥 Commits

Reviewing files that changed from the base of the PR and between e13c48f and 0ed1a3f.

📒 Files selected for processing: 4

• Library/Homebrew/livecheck/strategy/github_latest.rb
• docs/Brew-Livecheck.md
• docs/Cask-Cookbook.md
• docs/Formula-Cookbook.md

🚧 Files skipped from review as they are similar to previous changes: 1

• docs/Formula-Cookbook.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

[samford]

Thanks, Bevan!