Skip to content

chore: migrate installs-cache from docs to cycles-docs after repo rename#656

Merged
amavashev merged 1 commit into
mainfrom
chore/migrate-installs-cache-docs-to-cycles-docs
May 16, 2026
Merged

chore: migrate installs-cache from docs to cycles-docs after repo rename#656
amavashev merged 1 commit into
mainfrom
chore/migrate-installs-cache-docs-to-cycles-docs

Conversation

@amavashev
Copy link
Copy Markdown
Contributor

What

The repo `runcycles/docs` was renamed to `runcycles/cycles-docs`. `.vitepress/theme/installs-cache.json` still has the old name in both `clonesByRepo` and `releasesByRepo`. Renaming those keys in place avoids a double-count on the next scheduled run.

The bug (without this fix)

`fetchGithubClones` (in `installs.data.ts`) and `updateClones` (in `scripts/update-github-counts.mjs`) both:

  1. Call `listOrgRepos()`, which returns the live GitHub list — now contains `cycles-docs`, not `docs`.
  2. For `cycles-docs`, the cache lookup falls back to default `{ count: 0, lastSeenDay: '' }`.
  3. All 14 days in the `/traffic/clones` API window pass the `day > cached.lastSeenDay` check, so a fresh `cycles-docs` entry gets seeded with 14 days of clones in one bulk addition.
  4. The old `docs` key in `clonesByRepo` is preserved by `{ ...cachedByRepo }` (installs.data.ts:359; update-github-counts.mjs:108). Nothing iterates removed keys to migrate or prune them. It becomes a zombie at count=16064.
  5. `clones = Object.values(updated).reduce((a, b) => a + b.count, 0)` sums both the zombie `docs` (16064) and the freshly seeded `cycles-docs` (~14 days) — double-counting the overlap.

The displayed total (`total: 13319`) was not affected because clones are explicitly excluded from the displayed total (installs.data.ts:511). Only the homepage clones counter (`cache.clones`) was at risk.

The fix

Rename the cache keys directly: `docs` → `cycles-docs` in both `clonesByRepo` and `releasesByRepo`. Count and `lastSeenDay` cursor carry over unchanged, so:

  • The aggregate `clones` field stays at 70541 (sum verifies).
  • The next loader run reads `cycles-docs` from a populated entry with `lastSeenDay: '2026-05-14'` — only days strictly after that get added incrementally. No bulk re-seed.
  • The zombie `docs` key is gone.

Releases migration is cleanup-only (the cached value was 0, so no double-count, but the zombie key is cleared for tidiness).

Follow-up worth considering

The scripts have no rename-detection mechanism. If another repo is renamed in the future, the same bug recurs. Two paths:

  1. Recommended: Add a `REPO_RENAMES` map in `update-github-counts.mjs` that migrates cached entries from old to new names at the start of each run. Manual maintenance, but the safest approach (one line per rename).
  2. Riskier: Auto-prune cached keys not in the current `listRepos()` result. A temporary API failure or a repo briefly archived could wipe legitimate cached state.

Worth filing as a follow-up; for this PR, the one-off data migration is sufficient.

Test plan

  • `npm run build` succeeds with the migrated cache
  • After build, verify `clones` field in installs-cache.json still ≥ 70541 (the HWM guard at installs.data.ts:139–168 should preserve it)
  • Verify `clonesByRepo['cycles-docs']` is present with count=16064; `clonesByRepo['docs']` is absent
  • Verify homepage clones counter is unchanged
  • Confirm next scheduled run of `update-github-counts.mjs` adds only days > 2026-05-14 to `cycles-docs` (no 14-day bulk seed)

… rename

The org repo `runcycles/docs` was renamed to `runcycles/cycles-docs`.
`.vitepress/theme/installs-cache.json` still keyed the cached clones
(count: 16064) and releases (0) under the old name. Without this
migration, the next run of `installs.data.ts` (build-time loader) or
`scripts/update-github-counts.mjs` (scheduled refresh) would have
silently double-counted ~14 days of clone activity on the renamed
repo:

  1. `listOrgRepos()` returns the live list, which now contains
     `cycles-docs` (not `docs`).
  2. For `cycles-docs`, the cache lookup falls back to the default
     `{ count: 0, lastSeenDay: '' }` (or `'1970-01-01'` in the script).
  3. All 14 days in the `/traffic/clones` API window pass the
     `day > cached.lastSeenDay` check, so a fresh `cycles-docs` entry
     is seeded with 14 days of clones in one bulk addition.
  4. The old `docs` key is preserved by `{ ...cachedByRepo }` because
     nothing iterates removed keys. It becomes a zombie entry frozen
     at count=16064.
  5. The aggregate `clones` field = sum of all entries = old `docs`
     count + freshly seeded `cycles-docs` count, double-counting the
     overlapping 14 days.

This patch migrates the keys directly in the cache so the next loader
run reads `cycles-docs` from a populated entry (with the correct
lastSeenDay cursor) and only accumulates new days. No re-seed, no
zombie key, no double-count. The aggregate `clones` field (70541) is
unchanged because the key was renamed, not the value.

The displayed total (`total: 13319`) was not affected by this bug
because clones are explicitly excluded from the displayed total per
installs.data.ts:511. Only the homepage clones counter (cache.clones)
was at risk.

Releases migration is cleanup-only: the cached `docs` value was 0, so
no double-count, but removing the zombie key keeps the file tidy.

## Follow-up consideration

The script has no rename-detection mechanism. If another repo is
renamed in the future, the same bug recurs. Two options worth thinking
about:

1. A `REPO_RENAMES` map in `update-github-counts.mjs` that migrates
   cached entries from old to new names at the start of each run.
   Manual maintenance, but the safest approach.
2. An auto-prune step that drops cached keys not in the current
   `listRepos()` result. Dangerous — a temporary API failure or a
   repo briefly archived could wipe legitimate cached state.

Recommend option 1 if rename frequency increases; for now, a one-off
data migration is sufficient.
@amavashev amavashev merged commit 3364cb1 into main May 16, 2026
6 checks passed
@amavashev amavashev deleted the chore/migrate-installs-cache-docs-to-cycles-docs branch May 16, 2026 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant