feat: publish release calendar as JSON (RFD #100)

[John McCall (lowlydba)]

Pull Request

Prior, release calendar dates only existed as a markdown table, so pipelines and tools hardcoded them, and several docs examples hardcoded old release versions. Some of those versions are no longer in the public bucket, so the examples fail.

While the STAC exists for current/latest releases, we were lacking a well-known data file for future (and long-past) releases, i.e. a calendar. This publishes the calendar as data, renders the release pages from it, and moves the examples onto the existing release placeholder. It also opens the door for a client consumer package for further use programmatically by consumers.
Background in RFD 100.

Fixes #525
Fixes OvertureMaps/ops-team#588

What this means for maintenance

Each release used to mean (1) editing the schedule table, (2) moving a row into the history table, (3) adding the release notes link, (4) bumping the build fallback, and (5) checking examples for stale versions. Now:

• (1) Add entries to the JSON for the releases as scheduled
• (2) Publish the release notes as blog/YYYY-MM-DD-release-notes.mdx, and fill in the schema version once it's known
• 🎉 Nothing else: the schedule, history, links and fallback follow from the file, and examples pick up the latest release at build time

The steps are in CONTRIBUTING.

Release calendar as data

• static/release-calendar.json is a flat list of releases, served at the site root with a JSON Schema alongside it
• The release calendar page renders the upcoming schedule and the history from it, split by date
• The build fallback release is the newest shipped entry, and history rows link to the release notes when blog/YYYY-MM-DD-release-notes.mdx exists

Examples and notebook

The ibis, pandas, spark, wherobots and GERS tutorial examples use the __OVERTURE_RELEASE placeholder, resolved from STAC at build time. A CodeBlock theme wrapper makes it work in plain fenced blocks, which keeps the pages markdownlint-clean. The pandas notebook looks up the latest release from STAC, and its setup cells now run in a working order. Its geometry call is fixed for current DuckDB.

Also

• The six 2024 release notes posts are renamed to the standard filename so their links can be derived. The old /blog/<data version> URLs redirect
• Maintainer procedures moved from the README to CONTRIBUTING.md, and the README now covers consumers
• ajv is declared as a dev dependency for the schema test. It was already installed transitively

Testing

CI runs the new tests and the site build. It doesn't run the notebook: I ran it end to end with DuckDB 1.5.6 and JupySQL 0.11.1, not the older DuckDB it was written for.

[github-actions]

🗺️ Overture Docs preview is live!

🌍 Preview site	https://staging.overturemaps.org/docs/pr/565/index.html
🕐 Updated	Oct 08, 2026 19:11 UTC
📝 Commit	efc1937

Note

♻️ This preview updates automatically with each push to this PR.

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Max errors	Warnings	Elapsed time
✅ JAVASCRIPT	eslint	33		0		0	17.97s
✅ MARKDOWN	markdownlint	286		0		0	0.37s
✅ SQL	sqlfluff	79		0		0	4.88s

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@10.1.0 --custom-flavor-setup --custom-flavor-linters JAVASCRIPT_ES,MARKDOWN_MARKDOWNLINT,SQL_SQLFLUFF

Show us your support by starring ⭐ the repository

[Copilot]

🟡 Changes recommended

The JSON documentation contradicts its schema, null history values render incorrectly, and the Markdown lint configuration rejects an added blank line.

4 open findings

• Remove extra blank line violating MD012 · New
• Render TBD when historical release schemaVersion is null · New
• Validate release dates with JSON Schema date format · New
• Remove stale tutorial example with contradictory pinning · New

What changed in this PR

Publishes a machine-readable release calendar, renders release documentation from it, and replaces hardcoded release versions in examples.

Changes:

• Adds the release calendar, schema, validation, and dynamic tables.
• Centralizes release placeholders using STAC’s latest release.
• Normalizes historical release-note routes and maintainer documentation.

File	Description
static/​release-calendar.schema.json	Defines the calendar schema.
static/​release-calendar.json	Adds release history and schedule data.
static/​notebooks/​overture-duckdb-pandas-example.ipynb	Resolves the latest release from STAC.
src/​theme/​CodeBlock/​index.js	Resolves placeholders in fenced code blocks.
src/​releasePlaceholders.js	Centralizes placeholder replacement.
src/​releaseCalendar.js	Splits releases and builds note paths.
src/​components/​ReleaseCalendar.jsx	Renders schedule and history tables.
src/​components/​queryBuilder.js	Reuses the shared placeholder helper.
src/​__tests__/​releaseCalendar.test.js	Tests calendar behavior and validation.
README.md	Documents the JSON calendar.
package.json	Adds Ajv for schema tests.
package-lock.json	Locks the Ajv dependency.
docusaurus.config.js	Configures fallback releases, notes, and redirects.
docs/​release-calendar.mdx	Uses generated release tables.
docs/​gers/​gers-tutorial.mdx	Replaces pinned release versions.
docs/​examples/​wherobots.mdx	Uses the release placeholder.
docs/​examples/​spark.mdx	Uses the release placeholder.
docs/​examples/​pandas.mdx	Uses the release placeholder.
docs/​examples/​ibis.mdx	Uses the release placeholder.
CONTRIBUTING.md	Adds maintainer procedures.
blog/​2024-12-18-release-notes.mdx	Normalizes the release-note route.
blog/​2024-11-13-release-notes.mdx	Normalizes the release-note route.
blog/​2024-10-23-release-notes.mdx	Normalizes routes and an internal link.
blog/​2024-09-18-release-notes.mdx	Normalizes the release-note route.
blog/​2024-08-20-release-notes.mdx	Normalizes the release-note route.
blog/​2024-07-22-release-notes.mdx	Normalizes the release-note route.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[John McCall (lowlydba)]

Dana Bauer (@danabauer) Stephen Epps (@stepps00) could you look at the docs maintenance and upkeep side? The monthly steps are in CONTRIBUTING and summarized under "What this means for maintenance" in the description. What I'd like confirmed is that adding one JSON entry and publishing the release notes as blog/YYYY-MM-DD-release-notes.mdx fits how you run each release.

Eric Godwin (@ericgodwin) could you review the implementation design? The pieces I'd most like a second opinion on are the flat releases list that splits upcoming from shipped by date and the JSON Schema.