Skip to content

Preserve historical documentation in the version selector - #17

Merged
ikelaiah merged 1 commit into
mainfrom
docs/historical-versioned-documentation
Aug 24, 2026
Merged

Preserve historical documentation in the version selector#17
ikelaiah merged 1 commit into
mainfrom
docs/historical-versioned-documentation

Conversation

@ikelaiah

Copy link
Copy Markdown
Owner

Summary

Extend the versioned documentation site to the full tagged history so the version selector behaves like a time machine, matching the ChronoKit-FP approach.

  • Extend \docs/versions.json\ with \1.9.0, \1.8.1, \1.8.0, \1.7.0, and \1.0.0\ (all real tags; newest to oldest)
  • Auto-derive navigation for legacy releases that predate \layout.json\ from only the Markdown in their own tag
  • Generate a minimal landing page when a release shipped no \index.md, linking only to that release's real documents
  • Pre-flight every declared \source_ref\ with \git rev-parse\ and fail clearly when it does not resolve
  • Validate newest-to-oldest ordering, unique releases, current-release membership, and per-release \source_ref\ agreement in built sites
  • Document the versioned documentation policy in CONTRIBUTING.md

Historical accuracy principle: each release is built from its immutable Git tag; no current documentation is copied into old releases and sparse historical documentation is intentional (v1.0.0 renders exactly one cheat-sheet page).

No UI redesign: current modern releases keep their existing navigation hierarchy, typography, theme selector, search, banner, and page shell unchanged.

Test plan

  • \ ools/test_build_docs.py\ — 11 tests incl. legacy build without layout.json, sparse single-document release, selector history/current marking
  • \ ools/test_build_all_docs.py\ — 4 tests incl. unresolvable source_ref failure and mixed-era released-mode worktree build
  • \ ools/test_check_built_docs.py\ — 8 tests incl. ordering, duplicates, absent current, tampered source_ref
  • \ ools/test_check_docs.py, \ ools/check_docs.py, \ ools/test_docs_examples.py\
  • Full released-mode multi-version build: 7 paths / 41 pages
  • \check_built_docs.py\ passes on both released and development-preview sites; every version-selector target resolves

Extend the versioned documentation site to the full tagged history
(1.9.0, 1.8.1, 1.8.0, 1.7.0, 1.0.0), building every release only from
the Markdown that existed in its own immutable source_ref tag.

- Auto-derive navigation for legacy releases that predate layout.json
- Generate a minimal landing page when a release shipped no index.md
  linking only to that release's real documents
- Fail clearly when a declared source_ref does not resolve
- Validate newest-to-oldest ordering, unique releases, current-release
  membership, and per-release source_ref agreement in built sites
- Add regression tests for legacy builds, historical isolation, the
  version selector, and mixed-era released builds
- Document the versioned documentation policy in CONTRIBUTING.md
@ikelaiah ikelaiah self-assigned this Aug 24, 2026
@ikelaiah
ikelaiah merged commit 50d3c8a into main Aug 24, 2026
3 of 4 checks passed
@ikelaiah
ikelaiah deleted the docs/historical-versioned-documentation branch August 24, 2026 22:48
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