Skip to content

fix(docs): keep only the latest patch per minor in the version selector and choose the default by semver#286

Merged
Vulthil merged 1 commit into
mainfrom
fix/docs-version-pruning
Jul 4, 2026
Merged

fix(docs): keep only the latest patch per minor in the version selector and choose the default by semver#286
Vulthil merged 1 commit into
mainfrom
fix/docs-version-pruning

Conversation

@Vulthil

@Vulthil Vulthil commented Jul 4, 2026

Copy link
Copy Markdown
Owner

Summary

  • When eng/update_versions.py registers a stable version slug, it now prunes every other stable entry sharing the same (major, minor) line from versions.json and deletes that entry's directory under --root. main and prerelease slugs are never pruned and never trigger pruning, and pruning never crosses minor lines (registering 1.0.3 does not touch 1.1.x).
  • The site default is no longer set by --make-default directly. It is now always recomputed as the highest stable version present after pruning, falling back to main when no stable version exists. --make-default is still accepted (docs.yml passes it on every call) but is now advisory only, so a servicing release on an older minor line can no longer steal the site default away from a newer minor.

Behavior change to be aware of

Superseded patch docs directories are deleted from gh-pages when a newer patch in the same minor line is registered. Any deep link into a pruned patch's docs (e.g. /1.0.1/... after 1.0.2 ships) will 404. This is intentional — patch docs are strictly superseded — but is a visible change from today's behavior, where old patch directories accumulated forever.

Verification

No test harness exists for eng/, so this was verified by running the script against a scratch gh-pages tree for the scenarios called out in the acceptance criteria:

a) {main, 1.0.0, 1.0.1, default=1.0.1} + register 1.0.2

before: versions=[main, 1.0.1, 1.0.0], default=1.0.1, dirs=[1.0.0, 1.0.1, main]
after:  versions=[main, 1.0.2],        default=1.0.2, dirs=[main, 1.0.2]   redirect -> ./1.0.2/

b) {main, 1.0.2, 1.1.0, default=1.1.0} + register 1.0.3 --make-default true

before: versions=[main, 1.1.0, 1.0.2], default=1.1.0, dirs=[1.0.2, 1.1.0, main]
after:  versions=[main, 1.1.0, 1.0.3], default=1.1.0, dirs=[1.1.0, main, 1.0.3]  redirect unchanged -> ./1.1.0/

c) register main

before/after identical: versions=[main, 1.0.1, 1.0.0], default=1.0.1

d) register 1.2.0-preview

after: versions=[main, 1.2.0-preview(prerelease), 1.0.1, 1.0.0], default=1.0.1 (unchanged)

Backport to v1.0: yes -- #287

@Vulthil
Vulthil marked this pull request as ready for review July 4, 2026 11:38
@Vulthil
Vulthil merged commit 4833cf1 into main Jul 4, 2026
7 checks passed
@Vulthil
Vulthil deleted the fix/docs-version-pruning branch July 4, 2026 11:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant