[doc] Establish doc/redirects/current.yaml as the redirects source of truth by dstrodtman · Pull Request #63367 · ray-project/ray

dstrodtman · 2026-05-15T14:14:02Z

What this PR is

doc/redirects/current.yaml is the curated source of truth for the HTTP redirects configured on the anyscale-ray Read the Docs project (docs.ray.io), managed with rtd-redirects. This PR establishes the file and the README policy for changing redirects.

The original 287-rule bootstrap snapshot (a February 2023 bulk import, never cleaned) is preserved in this PR's history. The earlier review-bot findings (circular redirects, duplicate entries, a .rst typo) were properties of that historical snapshot and are resolved in the curated state.

Cleanup summary (May 15 - June 3, 2026)

287 -> 172 rules. 169 version-agnostic page rules plus 3 intentional version-pinned exact rules.
Every rule's target verified live (HTTP 200); broken, duplicate, shadowed, and test rules removed or retargeted.
All redirect chains flattened to single hops, anchors preserved.
All rules now return 301 (previously 99% returned 302).
Two prefix-rename groups consolidated into wildcard rules (/ray-core/tasks/patterns/*, /auto_examples/*).

Verification

rtd-redirects plan --file doc/redirects/current.yaml --strict against the live project: no changes and a clean validator run. The file mirrors production exactly.
End-to-end probes across every change category: 10/10 serve a single 301 hop to a 200 destination.

Policy

Details in doc/redirects/README.md: redirect changes go through this file via PR; dashboard edits are out-of-process; rtd-redirects plan audits drift; a maintainer runs apply after merge (CI automation planned).

[DOC-928] [DOC-947]

🤖 Generated with Claude Code

Bootstrap the on-disk snapshot of the 287 redirects currently configured on the anyscale-ray Read the Docs project. These files preserve the pre-investigation state so the API-side config can be restored if it drifts during validation work for the rtd-redirects tool. - current.yaml: ergonomic YAML produced by `rtd-redirects dump`. Intended to become the source of truth at doc/redirects/current.yaml once the redirect-management workflow lands (rtd-redirects PRD / DOC-844). - current.list.txt: one-line-per-redirect debug listing from `rtd-redirects list`. Verification artifact. - current.api.json: raw v3 API objects with pk, timestamps, and _links. Verification artifact and pre-mutation snapshot. The verification artifacts may be pruned before this PR is marked ready. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

gemini-code-assist

Code Review

This pull request migrates documentation redirects from a text-based list to a structured YAML configuration. The review identified several critical issues in the new YAML file, specifically circular redirects for the root path and the /en/latest/ wildcard pattern which would cause infinite loops. Feedback also highlighted a duplicate entry and a typo where a destination path incorrectly uses a .rst extension instead of .html.

gemini-code-assist · 2026-05-15T14:15:23Z

+- from: /en/latest/*
+  to: /en/latest/:splat
+  type: exact
+  status: 302


This wildcard redirect is circular (redirecting /en/latest/* to itself via :splat). This will cause infinite redirect loops for any path under /en/latest/ and should be removed from the configuration.

…OC-947] Adds two artifacts from the bootstrap cleanup pass at DOC-947 so future sessions can resume the work without rebuilding tooling. - doc/redirects/audit_live.py: one-off audit script that classifies every redirect against a fixed taxonomy (status_302, target_dead, chained_target, consolidatable, type_convertible, etc.), probes docs.ray.io for source/target liveness, and emits a CSV/Markdown/YAML/JSON action plan. Used to drive the 283 -> 184 cleanup. Documented in the strategy writeup at anyscale/docs:strategy/ray-docs/redirect-mgmt/bootstrap-cleanup.md. - doc/redirects/review_list.md: the 34 exact rules that survived the cleanup with broken or content-suspect targets. Each needs hand-picked replacement. Plus 3 intentionally version-pinned releases-X.Y.Z rules to leave as exact. Will be used for the remaining manual review work and the final 302->301 sweep before the cleanup workstream closes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

github-actions · 2026-05-30T12:42:29Z

This pull request has been automatically marked as stale because it has not had
any activity for 14 days. It will be closed in another 14 days if no further activity occurs.
Thank you for your contributions.

You can always ask for help on our discussion forum or Ray's public slack channel.

If you'd like to keep this open, just leave any comment, and the stale label will be removed.

dstrodtman · 2026-06-03T13:49:53Z

Keeping this open — the redirect-cleanup workstream behind this snapshot is active.

Context for the review-bot findings: current.yaml here is a point-in-time snapshot of the live ruleset before cleanup, preserved deliberately for rollback. The flagged circular redirects, duplicate entries, and .rst typo are properties of that historical state, not proposed configuration. The live ruleset has since been cleaned (287 → 184 rules). Remaining steps: manual review of the 34 rules in review_list.md, a 302 → 301 pass, then this snapshot gets replaced with the curated YAML and the PR leaves draft.

Regenerate doc/redirects/current.yaml from the cleaned-up live state of the anyscale-ray Read the Docs project: 172 rules (169 version-agnostic page rules plus 3 intentional version-pinned exact rules), all returning 301. Verified with `rtd-redirects plan --strict`: zero drift against production, validator clean (0 errors). Remove the stale bootstrap artifacts (current.api.json, current.list.txt, review_list.md) that described the pre-cleanup state; they remain available in git history. Keep audit_live.py for future audit passes. Add README.md documenting the source-of-truth policy: redirects change through this file via PR, and dashboard edits are out-of-process. [DOC-928] [DOC-947] Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

Cleared the description field on the two consolidated wildcard rules in the live RtD config and re-dumped; parity re-verified with rtd-redirects plan --strict (no changes). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

The audit_live.py one-off auditor drove the May-June 2026 redirect cleanup but isn't part of the redirects source-of-truth workflow, and it trips premerge lint. Remove it to keep this PR scoped to current.yaml and the policy README. Nothing is lost: the cleanup is summarized in the README and the pre-cleanup snapshot is preserved in git history. Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 54f3d36. Configure here.}

cursor · 2026-06-04T18:48:29Z

+  type: page
+- from: /data/dataset.html
+  to: /en/master/data/api/dataset.html
+  type: page


Page redirects pin master version

Medium Severity

Three type: page rules send every docs version to hard-coded /en/master/... destinations, while the README asks for version-less final targets and sibling rules for the same topics use version-relative paths.

Additional Locations (2)

doc/redirects/current.yaml#L253-L256

doc/redirects/current.yaml#L418-L421

^{Reviewed by Cursor Bugbot for commit 54f3d36. Configure here.}

## Why A 6-month GA4 audit of `docs.ray.io` found **2,017 out-of-support legacy-version paths receiving ~552K views with no redirect rule and no equivalent on current docs**. Under any legacy-cohort cutover, that traffic lands on 404s. This PR adds the redirect coverage for the bulk of that gap. ## What 21 `page` catch-all rules appended to `doc/redirects/current.yaml`, covering **~96% of the gap by views and by paths**. Each cluster lands on its nearest surviving section index: - **Autodoc / API refs** (RLlib `package_ref`, Serve, Data, Tune, Train, Ray Core, Observability) → that library's API reference index. - **Examples** (Ray AIR, Tune, Train, Ray Core) → the examples gallery. - **Restructured sections** (Kubernetes, Serve tutorials) → the section index. - **Deprecated, no current equivalent**: Ray AIR → AIR getting-started; Ray Workflows → Ray overview. - **Sphinx `_modules/` source views** → the Ray source on GitHub (a view-source request for a symbol that no longer exists is better served by GitHub search than a 404). - Three targeted `rllib-*` overrides precede the RLlib catch-all so high-traffic renamed pages land on their real equivalents. ## Design All rules are `type: page` with `force` omitted (defaults to `false`), so each **fires only when the path would 404**. Pages that still exist with the same name on any version resolve untouched; only moved/deleted/renamed paths hit the catch-all. This composes with the planned legacy-cohort cutover (`/en/releases-X.Y.Z/*` → `/en/latest/:splat`): the cutover preserves same-name paths, and these rules catch what no longer exists on current docs. ## Validation ``` rtd-redirects validate doc/redirects/current.yaml → 0 error, 49 warning ``` Zero ordering/shadow errors. The 49 chain warnings are benign: each is an existing rule whose `to` is a live page that happens to sit under one of the new section wildcards, which never fires on a live page given `force: false`. ## Notes - Follows the source-of-truth workflow established in #63367. - Application to Read the Docs is a manual maintainer step post-merge per `doc/redirects/README.md`. Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… truth (ray-project#63367) ## What this PR is `doc/redirects/current.yaml` is the curated source of truth for the HTTP redirects configured on the `anyscale-ray` Read the Docs project (docs.ray.io), managed with [rtd-redirects](https://github.com/anyscale/rtd-redirects). This PR establishes the file and the README policy for changing redirects. The original 287-rule bootstrap snapshot (a February 2023 bulk import, never cleaned) is preserved in this PR's history. The earlier review-bot findings (circular redirects, duplicate entries, a `.rst` typo) were properties of that historical snapshot and are resolved in the curated state. ## Cleanup summary (May 15 - June 3, 2026) - 287 -> 172 rules. 169 version-agnostic `page` rules plus 3 intentional version-pinned `exact` rules. - Every rule's target verified live (HTTP 200); broken, duplicate, shadowed, and test rules removed or retargeted. - All redirect chains flattened to single hops, anchors preserved. - All rules now return 301 (previously 99% returned 302). - Two prefix-rename groups consolidated into wildcard rules (`/ray-core/tasks/patterns/*`, `/auto_examples/*`). ## Verification - `rtd-redirects plan --file doc/redirects/current.yaml --strict` against the live project: **no changes** and a clean validator run. The file mirrors production exactly. - End-to-end probes across every change category: 10/10 serve a single 301 hop to a 200 destination. ## Policy Details in `doc/redirects/README.md`: redirect changes go through this file via PR; dashboard edits are out-of-process; `rtd-redirects plan` audits drift; a maintainer runs `apply` after merge (CI automation planned). [DOC-928] [DOC-947] 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…roject#63880) ## Why A 6-month GA4 audit of `docs.ray.io` found **2,017 out-of-support legacy-version paths receiving ~552K views with no redirect rule and no equivalent on current docs**. Under any legacy-cohort cutover, that traffic lands on 404s. This PR adds the redirect coverage for the bulk of that gap. ## What 21 `page` catch-all rules appended to `doc/redirects/current.yaml`, covering **~96% of the gap by views and by paths**. Each cluster lands on its nearest surviving section index: - **Autodoc / API refs** (RLlib `package_ref`, Serve, Data, Tune, Train, Ray Core, Observability) → that library's API reference index. - **Examples** (Ray AIR, Tune, Train, Ray Core) → the examples gallery. - **Restructured sections** (Kubernetes, Serve tutorials) → the section index. - **Deprecated, no current equivalent**: Ray AIR → AIR getting-started; Ray Workflows → Ray overview. - **Sphinx `_modules/` source views** → the Ray source on GitHub (a view-source request for a symbol that no longer exists is better served by GitHub search than a 404). - Three targeted `rllib-*` overrides precede the RLlib catch-all so high-traffic renamed pages land on their real equivalents. ## Design All rules are `type: page` with `force` omitted (defaults to `false`), so each **fires only when the path would 404**. Pages that still exist with the same name on any version resolve untouched; only moved/deleted/renamed paths hit the catch-all. This composes with the planned legacy-cohort cutover (`/en/releases-X.Y.Z/*` → `/en/latest/:splat`): the cutover preserves same-name paths, and these rules catch what no longer exists on current docs. ## Validation ``` rtd-redirects validate doc/redirects/current.yaml → 0 error, 49 warning ``` Zero ordering/shadow errors. The 49 chain warnings are benign: each is an existing rule whose `to` is a live page that happens to sit under one of the new section wildcards, which never fires on a live page given `force: false`. ## Notes - Follows the source-of-truth workflow established in ray-project#63367. - Application to Read the Docs is a manual maintainer step post-merge per `doc/redirects/README.md`. Signed-off-by: Douglas Strodtman <douglas@anyscale.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gemini-code-assist Bot reviewed May 15, 2026

View reviewed changes

github-actions Bot added the stale The issue is stale. It will be closed within 7 days unless there are further conversation label May 30, 2026

dstrodtman removed the stale The issue is stale. It will be closed within 7 days unless there are further conversation label Jun 3, 2026

dstrodtman changed the title ~~[doc] Snapshot anyscale-ray Read the Docs redirects~~ Jun 3, 2026

dstrodtman marked this pull request as ready for review June 3, 2026 15:41

dstrodtman requested a review from a team as a code owner June 3, 2026 15:41

cursor Bot reviewed Jun 3, 2026

View reviewed changes

Comment thread doc/redirects/audit_live.py Outdated

Comment thread doc/redirects/audit_live.py Outdated

Comment thread doc/redirects/audit_live.py Outdated

Comment thread doc/redirects/audit_live.py Outdated

ray-gardener Bot added docs An issue or change related to documentation core Issues that should be addressed in Ray Core labels Jun 3, 2026

cursor Bot reviewed Jun 4, 2026

View reviewed changes

dstrodtman added the go add ONLY when ready to merge, run all tests label Jun 4, 2026

elliot-barn approved these changes Jun 5, 2026

View reviewed changes

elliot-barn merged commit 8a2c20a into ray-project:master Jun 5, 2026
8 checks passed

dstrodtman mentioned this pull request Jun 5, 2026

[doc] Add legacy-version 404 redirect coverage to current.yaml #63880

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[doc] Establish doc/redirects/current.yaml as the redirects source of truth#63367

[doc] Establish doc/redirects/current.yaml as the redirects source of truth#63367
elliot-barn merged 5 commits into
ray-project:masterfrom
dstrodtman:doc-928-rtd-redirect-bootstrap

dstrodtman commented May 15, 2026 •

edited

Loading

gemini-code-assist Bot left a comment

gemini-code-assist Bot May 15, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 30, 2026

dstrodtman commented Jun 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

cursor Bot Jun 4, 2026

Uh oh!

Labels

2 participants

Uh oh!

Conversation

dstrodtman commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR is

Cleanup summary (May 15 - June 3, 2026)

Verification

Policy

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

gemini-code-assist Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 30, 2026

dstrodtman commented Jun 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

cursor Bot Jun 4, 2026

Choose a reason for hiding this comment

Page redirects pin master version

Uh oh!

Labels

2 participants

dstrodtman commented May 15, 2026 •

edited

Loading