From 0da61c183b625ea8983de77ed6755cf56a7a3627 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 17:27:27 +0000 Subject: [PATCH] docs: drop the permanently stale Migrations page `docs/migrations.md` inlined the frozen root `MIGRATIONS.md`, which by design holds only pre-fragment history: every migration written under the per-package `migrations.d/` convention was missing from the published page. An upgrade guide that silently omits the current migrations is worse than no page, because it reads as authoritative. Remove the page, its sidebar entry, and the `MIGRATIONS.md` path from the publisher's trigger (#882 already dropped it from the PR-side build). The alternative -- aggregating `packages/*/migrations.d/*.md` at build time -- is recorded in agents/reference/changelog-migrations.md as the option not taken; it needs a build step and a fragment ordering convention. Cross-references that pointed at the page (README, the root and per-package `MIGRATIONS.md` pointer stubs, docs/AGENTS.md) now point at the fragment dirs instead, so nothing links to a 404. Fixes #885 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014Wb5FG2GSbcfUMothCFZej --- .github/workflows/docs-release.yml | 1 - MIGRATIONS.md | 6 ++---- README.md | 2 +- agents/reference/changelog-migrations.md | 2 +- docs/.vitepress/config.ts | 3 +-- docs/AGENTS.md | 10 ++++------ docs/migrations.md | 5 ----- packages/python/MIGRATIONS.md | 3 +-- packages/rust/MIGRATIONS.md | 3 +-- packages/ts/MIGRATIONS.md | 3 +-- 10 files changed, 12 insertions(+), 26 deletions(-) delete mode 100644 docs/migrations.md diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml index ecc7ab81f..c45321e3a 100644 --- a/.github/workflows/docs-release.yml +++ b/.github/workflows/docs-release.yml @@ -8,7 +8,6 @@ on: branches: [main] paths: - 'docs/**' - - 'MIGRATIONS.md' - '.github/workflows/docs-release.yml' workflow_dispatch: diff --git a/MIGRATIONS.md b/MIGRATIONS.md index ff1e48f0d..c4274a304 100644 --- a/MIGRATIONS.md +++ b/MIGRATIONS.md @@ -9,11 +9,9 @@ migration entries are **per-package fragments** under five-subsection entry — so PRs never conflict on a shared file. See each package's `MIGRATIONS.md` (`packages/python`, `packages/ts`, `packages/rust`) and AGENTS.md, "Changelog and Migrations". This frozen archive is still the -source of truth for the pre-fragment history; the docs site -([Migrations](https://thekevinscott.github.io/dirsql/migrations)) surfaces it -via a VitePress include — do not edit the rendered page. +source of truth for the pre-fragment history. -See also: [`CHANGELOG.md`](https://github.com/thekevinscott/dirsql/blob/main/CHANGELOG.md) for the full release log. (The relative path is not used because this file is also included into the docs site via a VitePress include, where relative paths would break.) +See also: [`CHANGELOG.md`](CHANGELOG.md) for the full release log. ## Frozen history (pre-fragment) diff --git a/README.md b/README.md index 286ac4fa5..6be05dc43 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ The canonical facts -- flags, schemas, contracts, and API shapes: - [Stat columns & glob captures](docs/reference/columns.md) -- `path`, `basename`, `dir`, `ext`, `size`, `mtime`, `ctime`, and `{name}` captures - [HTTP API](docs/reference/http-api.md) -- `POST /query`, `GET /events`, errors - [SDK](docs/reference/sdk.md) -- `DirSQL`, `Table`, and `RowEvent` across Python, Rust, and TypeScript -- [Migrations](docs/migrations.md) -- upgrade notes for breaking changes; the canonical source is [`MIGRATIONS.md`](MIGRATIONS.md) at the repo root +- Migrations -- upgrade notes for breaking changes, one file per change under each package's `migrations.d/` ([python](packages/python/migrations.d/), [rust](packages/rust/migrations.d/), [ts](packages/ts/migrations.d/)); pre-fragment history is frozen in [`MIGRATIONS.md`](MIGRATIONS.md) at the repo root ## Explanation diff --git a/agents/reference/changelog-migrations.md b/agents/reference/changelog-migrations.md index 0500498ae..740fcd5fe 100644 --- a/agents/reference/changelog-migrations.md +++ b/agents/reference/changelog-migrations.md @@ -47,7 +47,7 @@ Migration fragments are per-package too, one file per changed package under `pac If a subsection does not apply, keep the heading and write `_None._`. Do not omit subsections. The template lives at the bottom of the frozen root `MIGRATIONS.md`. -The frozen root `MIGRATIONS.md` is surfaced on the docs site at `/migrations` via a VitePress include (`docs/migrations.md`). Do not edit the rendered page. +The frozen root `MIGRATIONS.md` is not published on the docs site: it holds only pre-fragment history, so a page built from it silently omits every migration written under the fragment convention -- an upgrade guide that looks authoritative and is not (#885). Aggregating `packages/*/migrations.d/*.md` into a page at build time is the option not taken; it needs a build step and a fragment ordering convention. **PR body requirement:** PRs that touch SDK code must contain the following block (checkboxes filled in): diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index bccf8c053..cd610f937 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -72,8 +72,7 @@ export default defineConfig({ { text: 'Columns', link: '/reference/columns' }, { text: 'Path-tables', link: '/reference/path-tables' }, { text: 'HTTP API', link: '/reference/http-api' }, - { text: 'SDK', link: '/reference/sdk' }, - { text: 'Migrations', link: '/migrations' } + { text: 'SDK', link: '/reference/sdk' } ] }, { diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 6f30bb723..676d5d422 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -60,15 +60,13 @@ migrated -- a page survives only if a slot wants its content): protocol, exit codes, timeouts); the columns model (named tables get their hook's output; path-tables get stat columns); the HTTP API; the SDK page (`reference/sdk.md`, one page with - Python/TypeScript/Rust code-groups -- the sole SDK home); plus the - Migrations include (`migrations.md`). + Python/TypeScript/Rust code-groups -- the sole SDK home). - **Explanation** (`explanation.md`) -- one page: how `dirsql` thinks (the filesystem is the source of truth; the database is a derived, ephemeral, read-only view; reconcile and diffing). Its canonical home is the root - `ARCHITECTURE.md`; - #374 surfaces it via an include page, the same mechanism - `docs/migrations.md` uses for `MIGRATIONS.md`. Edit the root file, never - a rendered include. + `ARCHITECTURE.md`; #374 surfaces it via a VitePress include + (``). Edit the root file, never a + rendered include. Working rules: diff --git a/docs/migrations.md b/docs/migrations.md deleted file mode 100644 index 0f3e6867c..000000000 --- a/docs/migrations.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Migrations ---- - - diff --git a/packages/python/MIGRATIONS.md b/packages/python/MIGRATIONS.md index da2b990ef..dcc5b932e 100644 --- a/packages/python/MIGRATIONS.md +++ b/packages/python/MIGRATIONS.md @@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under Nothing is assembled back into this file. Pre-fragment history (all packages) is frozen in the repository-root -[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at -[`/migrations`](https://thekevinscott.github.io/dirsql/migrations). +[`MIGRATIONS.md`](../../MIGRATIONS.md). diff --git a/packages/rust/MIGRATIONS.md b/packages/rust/MIGRATIONS.md index 58a8fcb98..720b4fa71 100644 --- a/packages/rust/MIGRATIONS.md +++ b/packages/rust/MIGRATIONS.md @@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under Nothing is assembled back into this file. Pre-fragment history (all packages) is frozen in the repository-root -[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at -[`/migrations`](https://thekevinscott.github.io/dirsql/migrations). +[`MIGRATIONS.md`](../../MIGRATIONS.md). diff --git a/packages/ts/MIGRATIONS.md b/packages/ts/MIGRATIONS.md index 13a868892..27f1feebb 100644 --- a/packages/ts/MIGRATIONS.md +++ b/packages/ts/MIGRATIONS.md @@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under Nothing is assembled back into this file. Pre-fragment history (all packages) is frozen in the repository-root -[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at -[`/migrations`](https://thekevinscott.github.io/dirsql/migrations). +[`MIGRATIONS.md`](../../MIGRATIONS.md).