DOC-6951 Backfill aliases for 256 pages that moved without one - #3769
Merged
Conversation
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history (5 new this commit):
Memory updated at fa4cb13 |
Contributor
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 5c86b1a. Configure here.
andy-stark-redis
force-pushed
the
DOC-6951-alias-backfill
branch
from
August 7, 2026 13:57
5c86b1a to
1cb4145
Compare
Contributor
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at 1cb4145 |
dwdougherty
approved these changes
Aug 7, 2026
andy-stark-redis
added a commit
that referenced
this pull request
Aug 7, 2026
Automates remembering to run the alias scanner, which is the only thing item C was ever about. The scan itself has been available as make check_aliases since the tooling landed. Post-merge on purpose, rather than the pull_request check originally planned. A PR-time check has to choose between being ignorable and being intrusive, and neither is worth it here: the fix is always the same mechanical edit, so author intent almost never matters, and the cases where it might -- a page retired rather than moved -- are already the ones the scanner refuses to touch. Running on every push to main instead costs about three seconds, needs no Hugo build, and keeps the window where an old URL 404s down to minutes rather than the days a scheduled-only sweep implies. Nobody sees anything on their own PR. The branch is regenerated from main on every run and force-pushed, so the PR always means the same thing: current main plus every alias currently missing. That makes repeated runs idempotent and stops a stale half-fix accumulating on a long-lived bot branch. An earlier draft tried to reuse and extend the existing fix branch, which meant switching branches with a dirty working tree -- fragile for no benefit. fetch-depth: 0 is load-bearing rather than tidy. The scanner reads git rename records, and in a shallow clone it finds none, reports zero moves and exits 0. Verified against a --depth 1 clone: a permanent green tick that never examines anything, which is the worst possible failure for a check like this. No other workflow in the repo sets it, and repo-memory.yml has already been caught by the same default once, needing fetch-depth: 2. Uses gh pr list --head rather than the gh search prs idiom the sync workflows use, because search goes through an eventually-consistent index and can miss a PR opened moments earlier, which would produce duplicates. Dry-run in a fresh clone: the scan and the exact git sequence produce a 202-file, 430-insertion commit on the fix branch, matching the backfill in #3769 line for line. Learned: checkout defaults to a depth-1 clone, in which this scanner silently passes; any history-reading check needs fetch-depth 0 and a test that it fails when it should Constraint: the fix branch is rebuilt from main and force-pushed every run, never extended, so the PR always represents main plus all currently-missing aliases Rejected: a pull_request check with annotations | intent almost never matters for a mechanical alias, and the cases where it would are already never auto-fixed Directive: merge this after the backfill in #3769, or its first run opens a competing PR containing the same 256 aliases Ticket: DOC-6951 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Restores 254 dead URLs across 200 pages. Every one belonged to a page renamed at some point in this repo's history without an alias for its old path, so the old URL has been returning 404 ever since. No prose was touched and no page moved: the only changes are aliases in frontmatter. 251 were generated by build/check_missing_aliases.py --all --fix. The other three are written by hand, and they are the part worth understanding, because the generator would have got them subtly wrong rather than obviously wrong. Both the Jedis and redis-py sections began as a single page that was later split up, so develop/clients/jedis.md became develop/clients/jedis/connect.md with a new _index.md alongside it. The file's lineage therefore runs from the old landing page to one child of the new section, and following it faithfully would have pointed a bookmark for the generic Java client page at a Jedis connection guide four renames later. The right target is the hub. Six URLs are affected and the same mistake is mirrored exactly in the Python docs, which review did not mention. Only three of the six needed anything. The other three were already declared on the hub pages, and had been surfacing in the scanner's collision bucket -- another page already claims this URL -- which turned out to be the tool pointing at the answer rather than at an obstacle. Worth remembering before treating a reported collision as a problem to solve. Left alone and reported rather than fixed: 24 moves whose old URL is a live page today, 25 collisions where another page claims the URL and Hugo would pick a winner arbitrarily, 6 chains crossing a page-into-section split, and 1 move onto a draft, which publishes nothing including its aliases. This set was regenerated against main after an unrelated restructure of the agent memory pages landed, which renamed or removed several of the files an earlier version of it had edited. Rebasing would have meant hand-resolving conflicts into aliases pointing at files that no longer exist; regenerating took one command and moved the count from 253 to 251, because that restructure also created 19 further moves of its own. Verified by building the corpus with and without this change and diffing the page sets, rather than by reading the diff, because three separate defects in the generator turned out to be invisible in every cheaper artifact. That gives exactly 254 new paths, every one an alias stub, no page lost, and no real page replaced by a stub. Hugo's own alias count moves 953 to 1207, and each of the three hand-written aliases resolves to its hub rather than to the leaf that inherited the file. Both builds emit the same ten REF_NOT_FOUND warnings, which come from the agent memory restructure already on main and are untouched by this change -- worth fixing, but not here. One case not to re-tidy: the alias on the 7.4.6-2 Kubernetes release note ends in a comma, because an author wrote a list without brackets. The comma is part of the published URL and that URL is live, so it is preserved exactly and a comma-free alias added beside it. Learned: three of the six wrong redirects were already correct on the hub pages and were surfacing as collisions, so the collision report was pointing at the answer rather than at a problem Directive: regenerate this set with make check_aliases_fix rather than hand-editing it, then diff two full builds -- but read the page-split report by hand, because lineage is not equivalence and the tool cannot choose a landing page for you Ticket: DOC-6951 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
andy-stark-redis
force-pushed
the
DOC-6951-alias-backfill
branch
from
August 10, 2026 09:39
1cb4145 to
fa4cb13
Compare
andy-stark-redis
added a commit
that referenced
this pull request
Aug 10, 2026
Automates remembering to run the alias scanner, which is the only thing item C was ever about. The scan itself has been available as make check_aliases since the tooling landed. Post-merge on purpose, rather than the pull_request check originally planned. A PR-time check has to choose between being ignorable and being intrusive, and neither is worth it here: the fix is always the same mechanical edit, so author intent almost never matters, and the cases where it might -- a page retired rather than moved -- are already the ones the scanner refuses to touch. Running on every push to main instead costs about three seconds, needs no Hugo build, and keeps the window where an old URL 404s down to minutes rather than the days a scheduled-only sweep implies. Nobody sees anything on their own PR. The branch is regenerated from main on every run and force-pushed, so the PR always means the same thing: current main plus every alias currently missing. That makes repeated runs idempotent and stops a stale half-fix accumulating on a long-lived bot branch. An earlier draft tried to reuse and extend the existing fix branch, which meant switching branches with a dirty working tree -- fragile for no benefit. fetch-depth: 0 is load-bearing rather than tidy. The scanner reads git rename records, and in a shallow clone it finds none, reports zero moves and exits 0. Verified against a --depth 1 clone: a permanent green tick that never examines anything, which is the worst possible failure for a check like this. No other workflow in the repo sets it, and repo-memory.yml has already been caught by the same default once, needing fetch-depth: 2. Uses gh pr list --head rather than the gh search prs idiom the sync workflows use, because search goes through an eventually-consistent index and can miss a PR opened moments earlier, which would produce duplicates. Dry-run in a fresh clone: the scan and the exact git sequence produce a 202-file, 430-insertion commit on the fix branch, matching the backfill in #3769 line for line. Learned: checkout defaults to a depth-1 clone, in which this scanner silently passes; any history-reading check needs fetch-depth 0 and a test that it fails when it should Constraint: the fix branch is rebuilt from main and force-pushed every run, never extended, so the PR always represents main plus all currently-missing aliases Rejected: a pull_request check with annotations | intent almost never matters for a mechanical alias, and the cases where it would are already never auto-fixed Directive: merge this after the backfill in #3769, or its first run opens a competing PR containing the same 256 aliases Ticket: DOC-6951 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 10, 2026
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
2 participants
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.
Restores 256 dead URLs — item B1 of DOC-6951.
Every URL here belonged to a page that was renamed at some point in this repo's history without an alias being added for its old path, so it has been returning 404 ever since. 253 were generated with
make check_aliases_fix; the remaining 3 are hand-written and are the interesting part (see below). No prose was touched and no page moved — the only changes arealiases:entries in frontmatter.Coverage of URL-changing moves goes from 291 of 598 to 544. The gaps run back to 2024, concentrated in the Redis Data Integration and RedisInsight restructures, with the rest scattered across individual moves.
Deliberately not fixed
Reported by the tool rather than acted on, because none has a safe automatic answer:
The three hand-written aliases
Review caught a class of redirect the generator gets subtly wrong, and it's worth understanding because it isn't a coding bug — it's lineage not being the same as equivalence.
Both the Jedis and redis-py sections began as a single page that was later split up:
develop/clients/jedis.mdbecamedevelop/clients/jedis/connect.mdwith a new_index.mdbeside it. The file's lineage therefore runs from the old landing page to one child of the new section — so following it faithfully would point a bookmark for the generic Java client page at a Jedis connection guide, four renames later. The right target is the hub.Six URLs are affected. Three needed nothing: they were already declared on the hub pages, and had been surfacing in the collision bucket — which turned out to be the tool saying the right page already owns this. The other three are added here, by hand, to
develop/clients/jedis/_index.mdanddevelop/clients/redis-py/_index.md.Reviewers spotted two instances on the Java side; the same mistake is mirrored exactly in the Python docs. Chains crossing a split are now never auto-fixed (#3767).
Verification — two full builds, diffed
The generator was wrong three times in ways that were invisible in every cheaper artifact, so this was checked by building the corpus with and without the change and diffing the page sets:
What each cheaper check missed
Worth recording, because it's the argument for the build step existing:
The page-set diff caught it as
index.htmlcoming out one short of the 256 added.One case not to re-tidy
The alias on
content/operate/kubernetes/release-notes/7-4-6-releases/7-4-6-2.mdends in a comma, because an author wrote a list without brackets. That comma is part of the published URL and.../7-4-6-2,/returns 200 today, while the comma-free spelling returns 404. It's preserved exactly, with a comma-free alias added beside it. An earlier revision of the generator "tidied" it and silently retired a live URL.Re-running this
Use
make check_aliases_fixrather than hand-editing, and diff two builds afterwards.🤖 Generated with Claude Code
Note
Low Risk
Documentation-only Hugo alias additions with no application or auth logic; main risk is an incorrect redirect target for a bookmarked URL, mitigated by build diffing and manual hub-alias review.
Overview
Adds
aliases:frontmatter entries across 256 docs pages so Hugo serves redirects for URLs that broke when pages were renamed or restructured without aliases (Redis Data Integration, RedisInsight release notes, RedisVL guides, client docs, Agent Memory paths, Amazon Bedrock/integrate/aws-bedrock/, and related operate/integrate moves).No body content or URL paths change—only redirect metadata. Most entries were produced by
make check_aliases_fix; three hub aliases were added manually ondevelop/clients/jedis/_index.mdanddevelop/clients/redis-py/_index.mdso old generic Java/Python client URLs land on section indexes instead of a child connect page after a page split.Also covers edge cases such as
/develop/clients/sce/→ SCH doc, comma-bearing K8s release-note URLs, and duplicate alias list normalization (e.g.redis-vl.md).Reviewed by Cursor Bugbot for commit fa4cb13. Bugbot is set up for automated code reviews on this repo. Configure here.