ops: re-seed installs cache + add runbook#522
Merged
Conversation
ROOT CAUSE: the committed installs-cache.json on main had regressed to the pre-PR-#515 schema: before: {"npm":4049,"pypi":1339,"crates":49,"ghcr":0, "maven":0,"total":44156,"fetchedAt":"..."} The 'ghcr:0' field, missing 'clones' / 'clonesByRepo' / 'releases' / 'ghPackages' fields are all symptoms of an old-schema cache file getting committed (likely from a stale local checkout or hand-edit during an unrelated session). EFFECT: HomeSocialProof.vue reads data.clones, gets 0 by default (field missing from cache), <span v-if=showClones> evaluates false, the entire 'repo clones' stat hides. Only the installs counter renders. Result: clones counter 'disappeared' from the homepage. FIX: re-ran 'npm run build' locally with GITHUB_TOKEN set (gh auth token) so the clones fetcher could populate per-repo day-cursor accumulators. New cache shape: after: {"npm":4049,"pypi":1339,"crates":49, "clones":35587, "clonesByRepo":{ /* 16 repos with count + lastSeenDay */ }, "releases":0,"releasesByRepo":{...}, "ghPackages":2672,"maven":0,"total":8109, "fetchedAt":"..."} Homepage will now render '8,109+ package installs · 35,587 repo clones'. PREVENTION: added .outreach/installs-cache-runbook.md documenting: - why the cache is committed (PyPI / clones APIs are rolling-window; cache holds the historical peak) - required env at build time (GITHUB_TOKEN with repo scope) - schema-regression detector (jq query to verify clones field exists) - CI checklist for the deploy pipeline - what to do if the clones counter disappears again The runbook lives in .outreach/ which is excluded from the published site (srcExclude in config.ts). Internal-facing only. OPEN QUESTION (for follow-up): the deploy pipeline likely needs GITHUB_TOKEN added if it does not have one already. Without a token in CI, every deploy build re-reads this committed cache without updating it — so the displayed numbers go stale instead of growing. The runbook flags this in the CI checklist.
The previous re-seed (commit 7aa7765) started the clones accumulator from an empty clonesByRepo because the committed cache on main had been wiped twice (commits 8fb04d5 and f3e8b24 wrote the old-schema {ghcr:0} cache that loses all accumulator state). A fresh seed from empty only captures the current 14-day API window, missing all activity from days that have rolled off. That's why the re-seed produced 35,587 — about 470 short of the historical peak of 36,057 from commit 35cd32b. Recovery: restored .vitepress/theme/installs-cache.json from git content of 35cd32b (the last cache that had clones=36057 with the full per-repo accumulator state, lastSeenDay=2026-04-29). Then ran npm run build with GITHUB_TOKEN; the day-cursor accumulator only added days strictly AFTER 2026-04-29 (i.e., one new day, 2026-04-30) on top of the 36,057 floor. Result: clones: 36,057 (restored peak) + 1,644 (Apr 30 new days) = 37,701 total: 8,109 (defensible, unchanged) Why the new total is GREATER than the original 36,057: between when 35cd32b was committed and the wipe, multiple build-time updates were LOST. The restoration only recovers the snapshot state from that specific commit; everything that should have accumulated in the days since (and was wiped) is gone permanently. Today's build adds Apr 30 on top of that snapshot. May 1 will accumulate on the next build. This is the best recovery possible without those lost intermediate states. Going forward, CI needs GITHUB_TOKEN AND the schema-regression detector from the runbook should run pre-commit to prevent another wipe.
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.
Brings the homepage clones counter back. Two changes:
Re-seed
.vitepress/theme/installs-cache.json— the committed cache had regressed to the pre-PR-installs counter: add GitHub clones + GitHub Packages, label 'installs + clones' #515 schema (noclonesfield,ghcr:0placeholder still present). Effect:HomeSocialProof.vuewas readingdata.clones→0→ thev-if="showClones"check hid the entire stat. Only the installs counter rendered.Add
.outreach/installs-cache-runbook.md— documents why this cache is committed (PyPI and GitHub clones APIs are rolling-window only; the cache holds the historical peak), the required CI env (GITHUB_TOKEN), a schema-regression detector, and what to do if this happens again.Before / after
ghcr:0, noclones)clonesByRepo, all fields)4,049+ package installs8,109+ package installsclones=0)35,587 repo clonesRoot cause hypothesis
The cache file is committed at every build that produces new HWMs. Somewhere along the way a stale or hand-edited cache file (with the old schema and a
total: 44156from after PR #515 baked in — a frankenstate) got committed tomain. That broke the homepage second stat starting from the next deploy build, because every deploy from then on read this regressed cache and propagated it.How this stays fixed
The runbook flags an open prevention item:
Verify Vercel / Netlify / Cloudflare Pages / GH Actions config exposes
GITHUB_TOKEN(orGH_TOKEN) withreposcope to the build environment. If yes: builds will keep the cache fresh on deploy. If no: the cache only refreshes when manually re-seeded (the play we just executed).Test plan
npm run buildlocally — verified, produces[installs] clones+35587(cache:35587)log linejq 'has("clones")' .vitepress/theme/installs-cache.jsonreturnstrue8,109+ package installs · 35,587 repo clonesGITHUB_TOKENis wired into the deploy pipeline (it's not optional — see runbook)