docs: record Homebrew API limitation blocking per-tap OS chart (#61) - #166
Open
mrbobbytables wants to merge 1 commit into
Open
docs: record Homebrew API limitation blocking per-tap OS chart (#61)#166mrbobbytables wants to merge 1 commit into
mrbobbytables wants to merge 1 commit into
Conversation
Independently re-verified (third check, after 2026-03-28 and 2026-08-08 prior findings) that formulae.brew.sh has no per-tap or per-formula OS-version analytics endpoint, and that ublue-os tap packages are not indexed on formulae.brew.sh at all. The per-tap OS distribution chart requested in castrojo#61 is not buildable against this API. Recording this as a project decision in skills/SKILL.md so future agents don't re-attempt the same dead-end investigation, and no placeholder/fake chart is implemented against non-existent data. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Issue #61 asks for a per-tap (ublue-os-specific) OS distribution chart, sourced by aggregating
formulae.brew.sh/api/analytics/os-version/{tap}/{formula}.jsonacross ublue-os packages.I independently re-verified the API surface before starting implementation (this is the third independent check, after the 2026-03-28 and 2026-08-08 investigations already recorded in the issue comments) and the conclusion holds:
formulae.brew.shonly exposes three analytics categories:install,install-on-request,build-error. There is noos-versioncategory and no per-formula/per-tap OS-version breakdown endpoint anywhere in the public API (confirmed againstHomebrew/formulae.brew.shdocs/api.mdand live 404s)./api/analytics/${CATEGORY}/homebrew-core/${DAYS}.json) is scoped tohomebrew-coreonly.ublue-os/homebrew-tapandublue-os/homebrew-experimental-tappackages are not indexed onformulae.brew.shat all —/api/formula/{name}.jsonreturns 404 for any ublue-os package.Given this, the feature as scoped in #61 is not buildable, and I'm not going to implement a placeholder/fake chart against data that doesn't exist.
stats-go/internal/osanalyticsalready uses the only available endpoint (the globalos-versionanalytics), which is whyOsSection.astrois correctly titled "Linux OS Distribution (all of Homebrew)" rather than ublue-os-specific.What this PR does
Documents this API limitation as a Project Decision in
skills/SKILL.md(alongside the existing Build Pages decisions) so future agents don't re-open the same dead-end investigation a fourth time, and so the reasoning for whyOsSection.astrois scoped the way it is stays discoverable.Recommendation for #61
I don't have write access to close issues in this repo. Recommend closing #61 as not-planned/won't-fix, per the two prior investigation comments on the issue. If a per-tap signal is wanted later, it would need to come from a different source entirely (e.g. GitHub tap traffic/clone stats, already collected by
stats fetch-homebrew) — not an OS-version breakdown, since none exists for third-party taps.No functional/behavioral code changes. No tests added (docs-only change).