Repository navigation
docs: redirect the retired v1.0-v9.0 docs URLs [OD-1153] - #2822
claudiacodacy wants to merge 1 commit into
Conversation
Retiring the versioned docs deleted v1.0-v9.0 and v2.0.387-deprecated from gh-pages without redirects, so old links and search results for them return 404. Add a build hook that writes a redirect page for each of those URLs, in the same format as the existing v10.0-v14.0 redirects, from a data file: - the v14.0 redirect's target where the same path exists there - the same path on the current site where it still exists - the Self-hosted section for old Self-hosted pages - /release-notes/ for old Enterprise release notes - the home page otherwise The list is one entry per page and version (9,505 URLs), too long for redirect_maps in mkdocs.yml. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 9 |
| Duplication | 0 |
AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.
TIP This summary will be updated as you push new changes.
There was a problem hiding this comment.
Pull Request Overview
The redirect hook has blocking portability and build-behavior issues: valid case-sensitive paths can be skipped, repeated dirty builds can reject the hook’s own output, and some URL paths cannot be materialized on Windows. The file is also complex and currently lacks coverage for these behaviors.
Codacy also found:
- Increased complexity in
theme/hooks/retired_version_redirects.py(delta 9), with no coverage report available.
Test suggestions
- Parse every TSV row and expand it into one redirect per listed version.
- Generate redirect HTML with canonical, meta-refresh, and JavaScript fragment-preserving redirects.
- Skip case-insensitive duplicate paths such as Chart/ and chart/.
- Raise an error when a generated redirect would overwrite an existing page.
- Verify all redirect destinations resolve to final pages rather than redirects.
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Parse every TSV row and expand it into one redirect per listed version.
2. Generate redirect HTML with canonical, meta-refresh, and JavaScript fragment-preserving redirects.
3. Skip case-insensitive duplicate paths such as Chart/ and chart/.
4. Raise an error when a generated redirect would overwrite an existing page.
5. Verify all redirect destinations resolve to final pages rather than redirects.
TIP How was this review? Give us feedback
| destination = site_dir / old_path / "index.html" | ||
| # Old versions published both /Chart/ and /chart/. On a case-insensitive | ||
| # file system (macOS) they are one file, so the second write is skipped. | ||
| if old_path.lower() in written: |
There was a problem hiding this comment.
🔴 HIGH RISK
On case-sensitive filesystems, the lowercase chart/ redirects are skipped after the Chart/ paths are written, resulting in 404s. Apply case-insensitive deduplication only where the filesystem requires it, while generating both variants where supported.
TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.
| if destination.exists(): | ||
| raise RuntimeError(f"Retired version redirect would overwrite a built page: {destination}") | ||
| written.add(old_path.lower()) | ||
| destination.parent.mkdir(parents=True, exist_ok=True) |
There was a problem hiding this comment.
🟡 MEDIUM RISK
Redirect generation fails on Windows for URL paths containing filesystem-invalid characters, such as quoted FAQ paths. Handle these URLs without requiring invalid directory or file names.
TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.
| if destination.exists(): | ||
| raise RuntimeError(f"Retired version redirect would overwrite a built page: {destination}") |
There was a problem hiding this comment.
🟡 MEDIUM RISK
A second mkdocs build --dirty fails when it encounters a redirect generated by the previous build. Distinguish previously generated redirects from actual existing pages so repeated dirty builds remain successful.
TIP React 👍 if this review is right, or reply with what's wrong and how it could be better to help improve the reviewer.
|
Closing: the redirects went straight to gh-pages instead (e528630), next to the existing v10.0–v17.0 stubs. |
Retiring the versioned docs (
cac1e47dcdongh-pages) replaced v10.0–v14.0 with redirects but deleted v1.0–v9.0 and v2.0.387-deprecated outright. Old links and search results for those URLs now return 404, for example/v2.0/repositories/what-are-the-different-grades-and-how-are-they-calculated/.This adds a build hook that writes a redirect page for each of those URLs: 676 paths across 28 versions, 9,505 URLs in all. The redirects use the same format as the existing v10.0–v14.0 ones, and the hook reads them from
data/retired-version-redirects.tsv, because the list is too long forredirect_maps.Each old path goes to the first of these that applies:
/release-notes/, for old Enterprise release notes from the Zendesk era/chart/, for old Self-hosted pagesRedirects to other redirects are followed to the final page, so no URL redirects twice.
Checked locally:
mkdocs buildpasses and every internal target exists in the build. The generated files are identical to the v14.0 redirect format. htmltest didn't run locally (no Docker), so CI covers it.Note: on macOS, old
Chart/andchart/paths are one file, so a local build writes 9,100 redirects. CI on Linux writes all 9,505.Out of scope: some existing root-level
hc/en-us/articles/…redirects ongh-pagespoint todocs.codacy.com/v2.0.386-deprecated/…, which also returns 404. This PR doesn't touch those.🤖 Generated with Claude Code