diff --git a/README.md b/README.md index 063adcf..a8075b2 100644 --- a/README.md +++ b/README.md @@ -371,9 +371,10 @@ release tags with NuGet versions — so publishing `3.0.0` retires the docs for `3.0.0-prerelease.N` on the next deploy with no manifest change. The channel returns by itself when the next prerelease is cut. Nothing here requires a clone-and-PR step before a deploy. Retired URLs are not left broken: the build -writes a `noindex` meta-refresh page for each one that points at the live page -with the same slug (GitHub Pages serves files only, so there is no redirect -config to declare). +writes a `noindex` meta-refresh page for each one that points at the live page with +the same slug, or — for a slug the reorganised live tree now publishes somewhere +else — at the new address the project declared in `docs.redirects` (GitHub Pages +serves files only, so there is no redirect config to declare). ## Agent skills diff --git a/docs/decisions/0009-documentation-channels.md b/docs/decisions/0009-documentation-channels.md index 470a0de..88d7dc6 100644 --- a/docs/decisions/0009-documentation-channels.md +++ b/docs/decisions/0009-documentation-channels.md @@ -113,13 +113,21 @@ A withheld channel must not turn its pages into 404s for readers following a bookmark. Because purview.dev is served from GitHub Pages (static files only, no redirect configuration), the build writes a meta-refresh page for every withheld channel URL — `/docs//prerelease/` and each -`/docs//prerelease//` — pointing at the live page with the same slug -(`lib/docs/redirects.ts`, run by `config/docs-redirects-integration.ts` at -`astro:build:done`). Each redirect carries `rel="canonical"`, `noindex, follow` -and `data-pagefind-ignore`, and is written outside Astro's route list so it never -enters the sitemap, `discover.json`, the llms bundles or the search index. The -redirect set is derived from the live channel's own slugs, so no generated -history has to survive between builds, and an existing page is never overwritten. +`/docs//prerelease//` (`lib/docs/redirects.ts`, run by +`config/docs-redirects-integration.ts` at `astro:build:done`). Each redirect +carries `rel="canonical"`, `noindex, follow` and `data-pagefind-ignore`, and is +written outside Astro's route list so it never enters the sitemap, `discover.json`, +the llms bundles or the search index. The redirect set is derived from the live +channel's own slugs, so no generated history has to survive between builds, and an +existing page is never overwritten. + +The retired tree is not synced, so a slug it published cannot be recovered from +anywhere: the live channel's slugs supply the destination for a page that still +has the same address, and the project's declared `docs.redirects` supplies it for a +page the reorganised live tree now publishes under a new one. A flat URL that only +ever existed in the retired channel therefore forwards straight to the live +channel's new address instead of to a second hop inside the withdrawn base. + ## Consequences diff --git a/docs/decisions/0011-documentation-folders.md b/docs/decisions/0011-documentation-folders.md index eb16c7e..53889a0 100644 --- a/docs/decisions/0011-documentation-folders.md +++ b/docs/decisions/0011-documentation-folders.md @@ -75,13 +75,15 @@ the newer tree, the new address is unpublished too, so forwarding the reader wou be forwarding into a 404 — the post-build link crawl fails the build on exactly that, which is how this was found. Both halves activate per page, at promotion. -A pair is emitted for every base the project publishes: the default channel at -`/docs//` and, when `live` and `prerelease` are both declared, the prerelease +A pair is emitted for every base the project publishes in this build: the default +channel at `/docs//` and, while both channels are published, the prerelease channel at `/docs//prerelease/`. The reorganised tree is usually published on the prerelease channel *first* — that is what a default-branch docs change is — and its readers follow URLs that move at the same moment the default channel's -do later. The same two guards decide which pairs are real, so a withheld channel -still writes nothing here; its URLs belong to the retired-channel redirects. +do later. The same two guards decide which pairs are real. A declared-but-withheld +channel is not a base at all: it publishes nothing in this build, so its retired +URLs belong to the retired-channel redirects, which forward a flat slug that only +ever existed there to the live channel's new address (ADR 0009). ### 4. The sidebar and the page show the tree the URL describes diff --git a/skills/docs-aggregation-rules/SKILL.md b/skills/docs-aggregation-rules/SKILL.md index b5e646c..95f17d6 100644 --- a/skills/docs-aggregation-rules/SKILL.md +++ b/skills/docs-aggregation-rules/SKILL.md @@ -70,11 +70,13 @@ A project may publish two views of its documentation: published: …` line, not an error) and the next prerelease restores it. Never remove the declaration just to stop publishing it. - **Retired URLs redirect to live.** For each withheld channel URL the build - writes a `noindex` meta-refresh page (canonical + `data-pagefind-ignore`) - pointing at the live page with the same slug — GitHub Pages serves files only, - so `_redirects` is not an option. These files are written at - `astro:build:done` (`config/docs-redirects-integration.ts`), outside Astro's - route list, so they stay out of the sitemap, `discover.json` and the llms + writes a `noindex` meta-refresh page (canonical + `data-pagefind-ignore`). A page + the live channel still publishes forwards slug-for-slug; a page that only ever + existed in the retired tree follows the project's declared `docs.redirects` to + the live channel's new address, so a bookmark never lands on a second redirect. + GitHub Pages serves files only, so `_redirects` is not an option. These files are + written at `astro:build:done` (`config/docs-redirects-integration.ts`), outside + Astro's route list, so they stay out of the sitemap, `discover.json` and the llms bundles. - Per-project `llms-full.txt` publishes the default channel only; `llms.txt` also links the prerelease channel when one exists. diff --git a/src/src/lib/docs/redirects.ts b/src/src/lib/docs/redirects.ts index 61db234..71f1ea6 100644 --- a/src/src/lib/docs/redirects.ts +++ b/src/src/lib/docs/redirects.ts @@ -56,9 +56,21 @@ export function redirectFilePath(redirect: DocChannelRedirect): string { } /** - * URLs of every declared-but-withheld channel, mapped to the live page with the - * same slug. Projects without channels, archived projects, and channels that are - * currently published produce no redirects. + * URLs of every declared-but-withheld channel, mapped to the live page that now + * carries the same content. Projects without channels, archived projects, and + * channels that are currently published produce no redirects. + * + * Two kinds of URL are retired, because a retired channel is not synced at all: + * + * - every slug the live channel publishes, forwarded slug-for-slug (`R/T` → `L/T`); + * - every slug the project declared as moved (`docs.redirects`), whose flat + * address only ever existed in the retired channel, forwarded to the live + * channel's new address (`R/F` → `L/T`). The live channel has no such page to + * copy the slug from, so the declared map is the only record that the old + * address ever resolved to that content. + * + * A moved pair whose old slug is still a live page is skipped: that URL is a real + * page on the canonical channel, so its own slug is the honest destination. */ export function retiredChannelRedirects( projects: readonly ResolvedProject[], @@ -79,18 +91,33 @@ export function retiredChannelRedirects( continue; } const published = new Set((entry?.channels ?? []).map((channel) => channel.id)); + const liveSlugs = new Set(live.pages.map((page) => page.slug)); + const moved = project.docs.source === 'github-path' ? (project.docs.redirects ?? {}) : {}; for (const channelId of DOC_CHANNELS) { if (declared[channelId] === undefined || published.has(channelId)) { continue; } + const emitted = new Set(); + const push = (from: string, to: string) => { + if (emitted.has(from)) { + return; + } + emitted.add(from); + redirects.push({ from, to }); + }; for (const page of live.pages) { - redirects.push({ - from: - page.slug === 'index' - ? `/docs/${project.id}/${channelId}/` - : `/docs/${project.id}/${channelId}/${page.slug}/`, - to: page.slug === 'index' ? `/docs/${project.id}/` : `/docs/${project.id}/${page.slug}/`, - }); + push( + page.slug === 'index' + ? `/docs/${project.id}/${channelId}/` + : `/docs/${project.id}/${channelId}/${page.slug}/`, + page.slug === 'index' ? `/docs/${project.id}/` : `/docs/${project.id}/${page.slug}/`, + ); + } + for (const [from, to] of Object.entries(moved)) { + if (!liveSlugs.has(to) || liveSlugs.has(from)) { + continue; + } + push(`/docs/${project.id}/${channelId}/${from}/`, `/docs/${project.id}/${to}/`); } } } @@ -106,14 +133,15 @@ export function retiredChannelRedirects( * the declaration timing-safe - while the `live` channel still reads an older tag, * the old slug is a real page and the redirect is simply not written. * - * Every published channel owns URLs of its own, so a move is forwarded from each - * base the project publishes: the default channel at `/docs//` and, when the - * project declares both channels, the prerelease one at `/docs//prerelease/`. - * A tree can be reorganised on the default branch long before the release that - * carries it is promoted, and the readers on the prerelease channel are following - * URLs that change at the same moment. Whether a pair is real is decided by the - * write guards exactly as for the default channel, so a withheld channel writes - * nothing here (its URLs are retired-channel redirects instead). + * Every channel this build publishes owns URLs of its own, so a move is forwarded + * from each published base: the default channel at `/docs//` and, when the + * project publishes it, the prerelease one at `/docs//prerelease/`. A tree can + * be reorganised on the default branch long before the release that carries it is + * promoted, and the readers on the prerelease channel are following URLs that + * change at the same moment. A declared-but-withheld channel is deliberately not a + * base: it publishes nothing in this build, so its retired addresses belong to + * `retiredChannelRedirects`, which forwards them to the live page (and, for a slug + * that only ever lived in the retired channel, to the live channel's new address). * * A repository may also record its own moves in `_redirects.yml` (ADR 0013). * That file is read at each channel's ref, so its pairs apply to that channel's @@ -143,22 +171,16 @@ export function docsPageRedirects( if (!project.docs || project.docs.source === 'readme' || project.status === 'archived') { continue; } + const entry = manifest?.projects.find((candidate) => candidate.projectId === project.id); if (project.docs.source === 'github-path') { const moved = project.docs.redirects ?? {}; - const bases = [`/docs/${project.id}`]; - // `prerelease` is only a second channel when `live` is declared with it; - // on its own it would be the default channel and own the canonical URLs. - const declared = project.docs.channels; - if (declared?.live !== undefined && declared.prerelease !== undefined) { - bases.push(`/docs/${project.id}/prerelease`); - } + const bases = publishedBases(project.id, entry); for (const [from, to] of Object.entries(moved)) { for (const base of bases) { add(base, from, to); } } } - const entry = manifest?.projects.find((candidate) => candidate.projectId === project.id); for (const channel of entry?.channels ?? []) { const base = channel.default ? `/docs/${project.id}` : `/docs/${project.id}/${channel.id}`; for (const [from, to] of Object.entries(channel.redirects ?? {})) { @@ -169,6 +191,27 @@ export function docsPageRedirects( return redirects; } +/** + * The site bases a project publishes in this build: its canonical + * `/docs//` base, plus one per extra published channel. + * + * Without a docs manifest the build cannot tell which channels survived the + * release gate, so only the canonical base is assumed: the writer's guards still + * refuse to shadow a real page or forward into a 404. + */ +function publishedBases( + projectId: string, + entry: DocsManifest['projects'][number] | undefined, +): string[] { + const canonical = `/docs/${projectId}`; + if (!entry || entry.channels.length === 0) { + return [canonical]; + } + return entry.channels.map((channel) => + channel.default ? canonical : `${canonical}/${channel.id}`, + ); +} + /** Site path of a page slug under a docs base; `index` is the base itself. */ function pagePath(base: string, slug: string): string { return slug === 'index' ? `${base}/` : `${base}/${slug.replace(/\/index$/, '')}/`; diff --git a/src/tests/dist/built-output.test.ts b/src/tests/dist/built-output.test.ts index f851bc9..d6bc6b6 100644 --- a/src/tests/dist/built-output.test.ts +++ b/src/tests/dist/built-output.test.ts @@ -354,6 +354,26 @@ describe('built use cases', () => { }); describe('built package versions', () => { + // Packages whose newest published version is a prerelease: they have never + // shipped a stable release, so their stable cell is empty by design. The set + // comes from the release data the site was built with rather than a pinned + // package, so a release turning one of them stable moves the test on instead of + // turning the build red for a product decision that was made on purpose. + const prereleaseOnly = (() => { + const index = getReleaseIndex(); + return loadProjects() + .filter((project) => project.status !== 'archived') + .flatMap((project) => + projectReleaseSummary(project, index.data, index.source) + .packages.filter((pkg) => pkg.latestStable === null && pkg.latestPrerelease !== null) + .map((pkg) => ({ + projectId: project.id, + packageId: pkg.packageId, + version: pkg.latestPrerelease!, + })), + ); + })(); + test('a package prerelease that trails its stable release is withheld', () => { const telemetry = loadProjects().find((project) => project.id === 'telemetry-sourcegenerator'); expect(telemetry).toBeDefined(); @@ -371,27 +391,19 @@ describe('built package versions', () => { expect(content).not.toContain(pkg!.latestPrerelease!); }); - test('a package with only prereleases is still listed', () => { - // Purview.ZodSharp.Http has never published a stable version. The package - // listing is not a stable-only view: the stable cell is empty and the - // prerelease version is shown (and pinned in its install snippet). - const zodsharp = loadProjects().find((project) => project.id === 'zodsharp'); - expect(zodsharp).toBeDefined(); - const index = getReleaseIndex(); - const summary = projectReleaseSummary(zodsharp!, index.data, index.source); - const pkg = summary.packages.find((entry) => entry.packageId === 'Purview.ZodSharp.Http'); - expect(pkg).toBeDefined(); - expect(pkg?.latestStable).toBeNull(); - // The package line keeps moving, so the expectation comes from the release - // data the site was built with rather than a pinned version. Otherwise every - // new prerelease turns a green build red without a product regression. - const latestPrerelease = pkg?.latestPrerelease; - expect(latestPrerelease).not.toBeNull(); - - const content = requireBuilt('projects/zodsharp/index.html'); - expect(content).toContain('Purview.ZodSharp.Http'); - expect(content).toContain(latestPrerelease!); - }); + test.skipIf(prereleaseOnly.length === 0)( + 'a package with only prereleases is still listed', + () => { + // The package listing is not a stable-only view: a package that has never + // published a stable version still appears, with its prerelease shown (and + // pinned in its install snippet) instead of an empty row. + for (const { projectId, packageId, version } of prereleaseOnly) { + const content = requireBuilt(`projects/${projectId}/index.html`); + expect(content, `${projectId} omits ${packageId}`).toContain(packageId); + expect(content, `${projectId} does not show ${packageId} ${version}`).toContain(version); + } + }, + ); }); describe('built llms links', () => { @@ -654,9 +666,17 @@ describe('built documentation channels', () => { expect(redirect).toContain(' { test('a published channel owns its URLs, so nothing is redirected', () => { expect(retiredChannelRedirects(projects, manifestWith(['live', 'prerelease']))).toEqual([]); @@ -120,6 +135,16 @@ describe('retired documentation channel redirects', () => { } }); + test('a moved page it used to publish points at the live address', () => { + // The reorganised live tree publishes `core-concepts` under its topic folder, + // but the flat slug only ever existed in the prerelease channel. The retired + // URL is forwarded straight to the live page rather than to another redirect. + expect(retiredChannelRedirects(projects, manifestWith(['live'], NESTED_PAGES))).toContainEqual({ + from: '/docs/zodsharp/prerelease/core-concepts/', + to: '/docs/zodsharp/concepts/core-concepts/', + }); + }); + test('a page that moved writes a redirect to its new home', () => { const dist = mkdtempSync(join(tmpdir(), 'purview-redirects-')); try { @@ -165,9 +190,9 @@ describe('moved documentation page redirects', () => { test('a move is forwarded on every channel that publishes the tree', () => { // The prerelease channel publishes the reorganised tree long before the // release that carries it is promoted, so its readers follow the same move: - // every pair exists under both bases, and the write guards decide which of - // them are real in the build at hand. - expect(docsPageRedirects(projects)).toContainEqual({ + // every pair exists under both published bases, and the write guards decide + // which of them are real in the build at hand. + expect(docsPageRedirects(projects, manifestWith(['live', 'prerelease']))).toContainEqual({ from: '/docs/zodsharp/prerelease/performance/', to: '/docs/zodsharp/prerelease/quality/performance/', title: 'This documentation page moved…', @@ -175,6 +200,17 @@ describe('moved documentation page redirects', () => { }); }); + test('a withheld channel is not a base for a move', () => { + // Once the line is promoted the prerelease tree is not published at all, so + // it owns no URL of its own: `retiredChannelRedirects` forwards what it used + // to serve, and the move must not write a second hop inside a dead base. + expect( + docsPageRedirects(projects, manifestWith(['live'])).filter((redirect) => + redirect.from.startsWith('/docs/zodsharp/prerelease/'), + ), + ).toEqual([]); + }); + test('a single-channel project forwards the canonical base only', () => { // Without a second declared channel there is no `/prerelease/` URL to // forward: the channel is the default one, and it owns `/docs//`.