Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 15 additions & 7 deletions docs/decisions/0009-documentation-channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<id>/prerelease/` and each
`/docs/<id>/prerelease/<page>/` — 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/<id>/prerelease/<page>/` (`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

Expand Down
10 changes: 6 additions & 4 deletions docs/decisions/0011-documentation-folders.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<id>/` 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/<id>/` and, while both channels are published, the prerelease
channel at `/docs/<id>/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

Expand Down
12 changes: 7 additions & 5 deletions skills/docs-aggregation-rules/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
95 changes: 69 additions & 26 deletions src/src/lib/docs/redirects.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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[],
Expand All @@ -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<string>();
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}/`);
}
}
}
Expand All @@ -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/<id>/` and, when the
* project declares both channels, the prerelease one at `/docs/<id>/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/<id>/` and, when the
* project publishes it, the prerelease one at `/docs/<id>/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
Expand Down Expand Up @@ -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 ?? {})) {
Expand All @@ -169,6 +191,27 @@ export function docsPageRedirects(
return redirects;
}

/**
* The site bases a project publishes in this build: its canonical
* `/docs/<id>/` 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$/, '')}/`;
Expand Down
66 changes: 43 additions & 23 deletions src/tests/dist/built-output.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -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', () => {
Expand Down Expand Up @@ -654,9 +666,17 @@ describe('built documentation channels', () => {
expect(redirect).toContain('<link rel="canonical" href="https://purview.dev/docs/zodsharp/"');
expect(redirect).toContain('<meta name="robots" content="noindex, follow"');
expect(redirect).toContain('data-pagefind-ignore');
// A deep page keeps its slug, so an old bookmark still lands on that page.
// An old bookmark of a page the live channel still publishes lands on that
// page, not on the retired tree.
expect(requireBuilt('docs/zodsharp/prerelease/concepts/core-concepts/index.html')).toContain(
'url=/docs/zodsharp/concepts/core-concepts/',
);
// A deep page whose slug only existed in the retired channel follows the
// move the project declared: the release that promoted the channel also
// reorganised its pages into topic folders, so the retired flat URL points
// straight at the live page rather than at a redirect inside the dead base.
expect(requireBuilt('docs/zodsharp/prerelease/core-concepts/index.html')).toContain(
'url=/docs/zodsharp/core-concepts/',
'url=/docs/zodsharp/concepts/core-concepts/',
);
},
);
Expand Down
Loading
Loading