Skip to content

docs: redirect the retired v1.0-v9.0 docs URLs [OD-1153] - #2822

Closed
claudiacodacy wants to merge 1 commit into
masterfrom
od-1153-retired-version-redirects
Closed

claudiacodacy wants to merge 1 commit into
masterfrom
od-1153-retired-version-redirects

Conversation

@claudiacodacy

@claudiacodacy claudiacodacy commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Retiring the versioned docs (cac1e47dcd on gh-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 for redirect_maps.

Each old path goes to the first of these that applies:

Target URLs
The page the v14.0 redirect at the same path points to 7,723
/release-notes/, for old Enterprise release notes from the Zendesk era 577
The Self-hosted section, /chart/, for old Self-hosted pages 400
The home page, for pages with no equivalent 805

Redirects to other redirects are followed to the final page, so no URL redirects twice.

Checked locally: mkdocs build passes 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/ and chart/ 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 on gh-pages point to docs.codacy.com/v2.0.386-deprecated/…, which also returns 404. This PR doesn't touch those.

🤖 Generated with Claude Code

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>
@claudiacodacy
claudiacodacy requested a review from a team as a code owner November 10, 2026 15:57
@codacy-production

Copy link
Copy Markdown
Contributor

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 9 complexity · 0 duplication

Metric Results
Complexity 9
Duplication 0

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

Run reviewer

TIP This summary will be updated as you push new changes.

@codacy-production codacy-production Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

⚠️ Resolve issues before merging

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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

Comment on lines +59 to +60
if destination.exists():
raise RuntimeError(f"Retired version redirect would overwrite a built page: {destination}")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

@github-actions
github-actions Bot temporarily deployed to Netlify November 10, 2026 15:59 Inactive
@claudiacodacy

Copy link
Copy Markdown
Contributor Author

Closing: the redirects went straight to gh-pages instead (e528630), next to the existing v10.0–v17.0 stubs.

@claudiacodacy
claudiacodacy deleted the od-1153-retired-version-redirects branch November 10, 2026 16:09

This branch was previously deployed

1 inactive deployment
Netlify — 40c89ee3 Deployed Nov 10, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant