Skip to content

fix(redirects): point a retired channel's flat URLs at the live page - #78

Merged
kieronlanning merged 1 commit into
mainfrom
fix/retired-channel-redirects
Nov 16, 2026
Merged

kieronlanning merged 1 commit into
mainfrom
fix/retired-channel-redirects

Conversation

@kieronlanning

Copy link
Copy Markdown
Contributor

Why

Deploy run 43901718339 failed validation after ZodSharp published stable v3.0.0 (14:40Z). That one release did two things at once:

  • it promoted the prerelease docs channel (stable caught up with 3.0.0-prerelease.6), and
  • its wiki carried the reorganisation into topic folders, so the live channel now publishes /docs/zodsharp/concepts/core-concepts/ and the flat /docs/zodsharp/core-concepts/ is gone.

Two assertions in src/tests/dist/built-output.test.ts caught it:

  1. a package with only prereleases is still listed — pinned to Purview.ZodSharp.Http, which now has a stable 3.0.0.
  2. a promoted channel redirects its retired URLs to the live pages — the retired flat URL forwarded to /docs/zodsharp/prerelease/concepts/core-concepts/, i.e. a redirect pointing at another redirect inside a channel that is no longer published.

The second is a real bug, not a stale test. The retired-channel pass runs first and writes prerelease/<new slug> for every live page; writeDocsPageRedirects then treats those freshly written files as "published destinations" (its guard is a filesystem check) and writes the flat retired URL into the dead base.

What changed

src/lib/docs/redirects.ts

  • docsPageRedirects forwards a move only from the bases the build publishes (taken from the docs manifest's channels). A declared-but-withheld channel is not a base.
  • retiredChannelRedirects also forwards the slugs that only ever existed in the retired tree: a docs.redirects pair whose destination the live channel publishes becomes R/F → L/T, so /docs/zodsharp/prerelease/core-concepts/ lands directly on /docs/zodsharp/concepts/core-concepts/. A pair whose old slug is still a live page is skipped.

Tests and docs

  • tests/unit/docs-redirects.test.ts: coverage for "a withheld channel is not a base for a move" and "a moved page it used to publish points at the live address"; the published-channel test now passes a manifest.
  • tests/dist/built-output.test.ts: the prerelease-only package test derives its subject from the build's release data (today event-sourcing, containers, astroc4) instead of pinning a package, so a release that makes one stable moves the test on rather than reddening a deliberate product change.
  • README.md, ADR 0009 §5, ADR 0011 §3 and skills/docs-aggregation-rules/SKILL.md now describe the published-base rule and the single-hop retired URL.

Verification

just validate passes locally in full (format, lint, astro check, 454 unit tests, catalogue check, build, discovery/SEO/link/generated checks, 48 dist tests with 6 skips). The rebuilt site writes 63 retired + 74 moved redirects, and both the nested and the flat retired ZodSharp URLs resolve to the live page in one hop.

Follow-up for the product repo: the comment above Purview.ZodSharp.Http in purview-dev/zodsharp's .config/purview-docs.yml still says "Published only as prereleases today".

ZodSharp's stable 3.0.0 promoted its prerelease channel, and the same release
reorganised the docs into topic folders. The retired-channel pass runs first, so
`writeDocsPageRedirects` mistook those freshly written redirect files for
published pages and emitted a second hop inside the withdrawn base:

  /docs/<id>/prerelease/<old>/ -> /docs/<id>/prerelease/<new>/

A move is now forwarded only from the bases this build publishes, and a retired
channel forwards a slug that only ever existed in its tree straight to the live
channel's new address.

The prerelease-only package test takes its subject from the release data instead
of pinning Purview.ZodSharp.Http, which shipped 3.0.0.
@kieronlanning
kieronlanning merged commit d6b2c7f into main Nov 16, 2026
1 check passed
@kieronlanning
kieronlanning deleted the fix/retired-channel-redirects branch November 16, 2026 17:16
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