chore: migrate installs-cache from docs to cycles-docs after repo rename#656
Merged
Merged
Conversation
… 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.
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
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.
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:
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:
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:
Worth filing as a follow-up; for this PR, the one-off data migration is sufficient.
Test plan