Repository navigation
Docs site publishes a permanently stale Migrations page #885
Description
What
docs/migrations.md is a VitePress stub that inlines the frozen root file:
---
title: Migrations
---
<!--@include: ../MIGRATIONS.md-->Root MIGRATIONS.md is frozen — its own header says so, and AGENTS.md confirms it: new migration entries are per-package fragments under packages/<pkg>/migrations.d/, one file per breaking change.
Nothing publishes those fragments. So the docs site's Migrations page renders only the pre-fragment history and has been going stale since the fragment convention landed. A reader upgrading dirsql sees an upgrade guide that silently omits every migration written under the current convention — which is worse than having no page at all, because the page looks authoritative.
Fix
Remove the Migrations page from the docs site: delete docs/migrations.md and drop MIGRATIONS.md from docs-deploy.yml's paths:.
The alternative — aggregating packages/*/migrations.d/*.md into the page at build time — keeps the page accurate but adds a build step and a fragment ordering convention. Recorded here as the option not taken, so the decision is visible if someone revisits it.
Notes
MIGRATIONS.mdwas already dropped from the PR-side docs build trigger in ci: add docs-ci, rename the docs publisher to docs-release #882 for this reason: it watches a file that is never supposed to change again.- The publisher (
docs-deploy.yml, renamed fromdocs.ymlin ci: add docs-ci, rename the docs publisher to docs-release #882) still listsMIGRATIONS.md. That entry goes away with this fix. - Root
CHANGELOG.mdis frozen the same way, but the docs site does not include it, so it is unaffected.
Activity
thekevinbot commentedon Aug 20, 2026
Correction: the publisher is
docs-release.yml(#932 item 5)This issue's Fix and Notes sections both name the publisher
docs-deploy.yml. No such file exists —#882renameddocs.ymltodocs-release.yml, and that is the workflow whosepaths:carried theMIGRATIONS.mdentry. Read everydocs-deploy.ymlabove asdocs-release.yml.The fix landed correctly regardless (#967 dropped
docs/migrations.mdand theMIGRATIONS.mdtrigger), so this is a record correction, not reopened work.The asymmetry this closed, stated so it is not re-added piecemeal
Before #967 the two docs workflows disagreed about one file:
MIGRATIONS.mdinpaths:?docs-ci.ymlpull_requestdocs-release.ymlpushtomainSo a
MIGRATIONS.mdedit showed zero checks on its PR and then ran the publisher onmain— exactly the pre-#882 shapedocs-ci.ymlwas created to close, surviving for one file. The fix resolved it by removing the trigger rather than adding one, which is the right direction given the file is frozen. AddingMIGRATIONS.mdback to either workflow'spaths:would re-open the asymmetry; both entries are gone on purpose and neither should return alone.Current state on
main, both verified:docs-ci.yml—paths: ['docs/**', '.github/workflows/docs-ci.yml']docs-release.yml—paths: ['docs/**', '.github/workflows/docs-release.yml']The self-path gap noted at the end of #932 item 5 (
docs-ci.ymlmissing its own file frompaths:) is also closed — it is present above.Generated by Claude Code