Superset's docs site keeps `lastVersion: 'current'` in every section so
the canonical URLs (`/docs/...`, `/admin-docs/...`, etc.) always render
master content, with cut versions accessible only via their explicit
version segment. The script's previous "auto-bump on first cut"
behavior was a generic Docusaurus default that doesn't match this
intent — for a section's first cut it would silently set lastVersion
to the new version, redirecting the canonical URL to the historical
snapshot.
Drop the auto-bump. Operators who want the new version to become the
canonical URL can edit versions-config.json after cutting.
Two related fixes to make the version cut self-contained and to clean
up after itself.
1. addVersion now runs `generate:smart` before snapshotting, so the
versioned copy captures fresh database pages (from engine spec
metadata), API reference (from openapi.json), and component pages
(from Storybook stories) rather than whatever happened to be on
disk. Added a --skip-generate flag for canonical release cuts where
the operator has placed the `database-diagnostics` artifact from a
green Python-Integration CI run at docs/src/data/databases.json and
wants to preserve the full Flask-context diagnostics rather than
regenerate locally.
2. removeVersion previously left an empty `<section>_versions.json`
file (`[]`) on disk when removing the last version. Docusaurus
would then snapshot that empty file back into content directories
on the next cut. (This is how the orphan files this PR already
cleans up — docs/components/versions.json and
docs/developer_docs/versions.json — got accidentally tracked.) The
remove path now deletes the file when it becomes empty.
Documented the cut prerequisites in docs/README.md ("Before You Cut")
and docs/DOCS_CLAUDE.md.
Extend freezeDataImports to also handle MDX imports that use the
Docusaurus `@site/` alias (e.g. feature-flags.mdx imports
`@site/static/feature-flags.json` to render the feature-flag tables).
Previously these were skipped because the regex only matched escaping
relative paths, so the snapshot kept reading the live JSON — meaning a
6.1.0 snapshot would silently grow new flags every time someone added
one in master.
The freeze now matches both prefixes:
- `from '../../foo/bar.json'` — relative escape (existing)
- `from '@site/static/foo.json'` — site-root alias (new)
`@site/` always resolves against the docs root, so we don't need the
depth check; instead we just skip any import that resolves inside the
section root (which would be copied with the section anyway).
Verified end-to-end with a throwaway admin_docs cut: the snapshot's
feature-flags page renders all 62 current feature flags from a frozen
JSON, alongside the country-map-tools freeze.
MDX files can import JSON/YAML data from outside the section (e.g.
admin_docs/configuration/country-map-tools.mdx imports
../../data/countries.json). Without intervention, the snapshot keeps
reading the live data file, so the historical version's content
silently changes whenever the data file is updated upstream.
Add a freezeDataImports step to manage-versions.mjs that runs at cut
time, before the depth-aware path rewriter:
- Walks the freshly-snapshotted section dir
- For each .md/.mdx file, finds escaping JSON/YAML imports (one or more
../) and resolves them against the file's original location
- Copies the resolved file into <snapshot>/_versioned_data/, preserving
its path relative to docs/ (the underscore prefix keeps Docusaurus
from treating it as content)
- Rewrites the import to point at the snapshot-local copy
Verified end-to-end with a throwaway admin_docs cut: the snapshot's
country-map-tools page renders all 201 countries from a frozen JSON,
and a subsequent edit to the live docs/data/countries.json does not
affect the snapshot's rendered output.
Tooling-only prep for the upcoming docs version cut. Snapshots will land
in a follow-up PR.
- Finish the developer_portal -> developer_docs rename: update package.json
scripts, manage-versions.mjs usage strings, DocVersionBadge plugin id list
(replaces bogus 'tutorials' and 'developer_portal' ids with the real
'default', 'components', 'admin_docs', 'developer_docs'), DocVersionBanner
dead branch, DOCS_CLAUDE.md, README.md
- Add admin_docs version add/remove scripts (which previously didn't exist)
- Generalize fixVersionedImports in manage-versions.mjs to walk every
section's snapshot dir with a depth-aware regex, and skip fenced code
blocks; replaces the previous hard-coded two-file list
- Remove orphan files: developer_portal_versions.json, tutorials_versions.json
(no such plugin), and the empty docs/components/versions.json and
docs/developer_docs/versions.json that were accidentally tracked inside
content directories
- Exclude auto-generated sidebar.js and sidebar.ts from the ASF license check
(these are produced by docs/scripts/convert-api-sidebar.mjs from the
OpenAPI spec, and a future version cut would otherwise commit them)
