DOC-6951 Backfill aliases for 256 pages that moved without one - #3769
Open
andy-stark-redis wants to merge 1 commit into
Open
DOC-6951 Backfill aliases for 256 pages that moved without one#3769andy-stark-redis wants to merge 1 commit into
andy-stark-redis wants to merge 1 commit into
Conversation
Contributor
Contributor
🧠 Redis MemoryFound 5 related items from repository history:
Memory updated at 5c86b1a |
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.
Restores 256 dead URLs. 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. 253 were generated by build/check_missing_aliases.py --all --fix; the remaining 3 are written by hand and are the interesting part. No prose was touched and no page moved. The only changes are aliases in frontmatter. The three hand-written ones are on the Jedis and redis-py hub pages, and they are there because the generator would have got them subtly wrong. Both client 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. Reviewers caught two instances on the Java side; the same mistake is mirrored exactly in the Python docs. Six URLs are affected and only three needed anything, because the other three were already declared on the hub pages. Those had been surfacing as collisions -- the tool reporting that another page already claims this URL -- which turned out to be it saying the right page already owns it. Worth remembering before treating a collision as an obstacle. Deliberately left alone and reported rather than fixed: 22 moves whose old URL is a live page today, 25 collisions where another page claims the URL and Hugo would pick one arbitrarily, 6 chains crossing a page-into-section split, and 1 move onto a draft, which publishes nothing including its aliases. Verified by building the corpus with and without this change and diffing the page sets, rather than by reading the diff: exactly 256 new paths, every one an alias stub, no page lost, no real page replaced by a stub. Both builds are warning-free, Hugo's alias count moves 929 to 1185, and each of the three hand-written aliases resolves to its hub rather than to the leaf that inherited the file. 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 showing up as collisions, so the collision report was pointing at the answer rather than at a problem Directive: regenerate with make check_aliases_fix rather than hand-editing this set, then diff two 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 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>
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 redirect metadata only; no application, auth, or runtime behavior changes.
Overview
Adds
aliases:entries in Hugo frontmatter across 256 markdown pages so former URLs redirect instead of 404ing after past doc moves. No pages were relocated and no body copy changed—only frontmatter.Coverage spans Agent Memory (
/develop/ai/agent-memory/→ context-engine paths), RedisVL guides (old/integrate/redisvl/...and shortened/develop/ai/redisvl/user_guide/...paths), client docs (/develop/connect/...), RedisInsight release notes (/develop/connect/insight/...), RDI / write-behind trees, Amazon Bedrock (/integrate/aws-bedrock/), Redis Cloud (Agent Memory, BYOC, subscription view URLs), and assorted K8s/RS/RC release-note aliases.One edge case is preserved on
7-4-6-2.md: a comma-suffixed alias (.../7-4-6-2,/) stays as-is because that spelling is a live URL today.Reviewed by Cursor Bugbot for commit 1cb4145. Bugbot is set up for automated code reviews on this repo. Configure here.