diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..dd4945e73 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing + +Maintainer procedures for this repository. For what the repository contains and how to run it locally, see the [README](README.md). + +- [Release calendar](#release-calendar) +- [Schema reference](#schema-reference) + - [Adding a schema version](#adding-a-schema-version) + - [Schema PR previews](#schema-pr-previews) +- [OG image cache](#og-image-cache) + +## Release calendar + +`static/release-calendar.json` is the source of truth for release dates, and the `/release-calendar` page renders from it (`src/components/ReleaseCalendar.jsx`). Its shape is documented in the [README](README.md#release-calendar), and `static/release-calendar.schema.json` validates it. + +Each month, add an entry for the release that's three to four months out, so at least three upcoming releases are listed. Set `majorChangeMonth` to true for March, June, September, and December. After a release ships, fill in `schemaVersion` if it was still `null`, and publish the release notes as `blog/YYYY-MM-DD-release-notes.mdx`. The history table links the data version to that post automatically, and shows plain text when there isn't one. Entries move from the schedule to the history table by date, so nothing else needs editing. The change shows up on the next deploy. + +The fallback release in `docusaurus.config.js` (`getLatestOvertureRelease()`) is the newest shipped entry in this file. It's only used when the STAC catalog is unreachable at build time. + +Don't hardcode the current release in docs examples. Use the `__OVERTURE_RELEASE` placeholder, which resolves the latest release from [STAC](https://stac.overturemaps.org/) at build time. It works in plain fenced code blocks and in the `QueryBuilder` component. Pin a version only when the surrounding text depends on that exact release. + +## Schema reference + +The reference pages under `docs.overturemaps.org/schema` are generated from the Pydantic models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema). + +The schema reference is its own [versioned Docusaurus docs instance](https://docusaurus.io/docs/versioning) (plugin id `schema`, config in `docusaurus.config.js`, sidebar in `sidebars-schema.js`), separate from the main `docs/` instance. Only released schema tags are published; there is no rolling "latest" built from `main`. The newest tag in `schema_versions.json` is served at `/schema/`, older tags at `/schema/vX.Y.Z/`, and a version dropdown appears in the navbar on schema pages only. + +Snapshots are generated once per tag and committed under `schema_versioned_docs/version-vX.Y.Z/`. Builds do not call the schema generator, so a production deploy only ever changes the schema pages when a new snapshot lands here. + +**A typo or error under `docs.overturemaps.org/schema` is not fixable in this repository.** Open an issue or PR against the docstrings/models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema) instead; the fix appears in the next release's snapshot. Re-snapshotting an existing tag is possible (delete its three artifacts and re-run the script below) but pointless unless the tag itself moved. + +The overview page (`schema/index.md`) is copied into each snapshot when it's created. Edits to it need to be applied to the `index.md` in each `schema_versioned_docs/version-*/` too. + +### Adding a schema version + +Run this after a `vX.Y.Z` tag is published in [OvertureMaps/schema](https://github.com/OvertureMaps/schema/releases). It needs `git`, [`uv`](https://docs.astral.sh/uv/), and `npm install` already done. + +```shell +npm run add-schema-version -- v2.0.0 +``` + +The script (`scripts/add-schema-version.mjs`) clones the schema repo at that tag, runs its `overture-codegen` into `schema/reference/`, then runs `docusaurus docs:version:schema `, which writes: + +- `schema_versioned_docs/version-/` (with links into the schema repo pinned to the tag) +- `schema_versioned_sidebars/version--sidebars.json` +- an entry in `schema_versions.json` (kept sorted newest-first; the first entry is what `/schema/` serves) + +Commit those three and open a PR. `schema/reference/` is cleaned up afterwards. + +Only tags that ship the `overture-schema-codegen` package (v1.17.0 and later) can be added; earlier releases were JSON Schema and have no generator. The script refuses tags that don't match `vX.Y.Z` or are already in `schema_versions.json`. + +### Schema PR previews + +The schema repo's PR preview workflow checks out this repo, generates Markdown from the PR branch into `schema/reference/`, and builds with `SCHEMA_PREVIEW=true`. In that mode the `schema` instance builds only the `current` version from `schema/reference/` at `/schema/`; committed snapshots, the version dropdown, blog, and community pages are skipped. + +## OG image cache + +The community page displays project cards with images. Each entry in `community/community-projects.json` can include an optional `"image"` field. For entries without one, the site falls back to a cached `og:image` fetched from the project's URL. + +The cache lives in `community/og-image-cache.json` and is committed to the repository so CI builds never make external HTTP requests. + +**When to run it:** after adding or updating entries in `community-projects.json`. + +```shell +npm run fetch-og +``` + +The script (`scripts/fetch-og-images.mjs`): + +1. Skips entries that already have an explicit `"image"` field +2. Re-validates any previously cached non-empty URLs via a HEAD request (`Content-Type: image/*`) and clears invalid ones +3. Fetches the HTML for uncached entries, extracts `og:image`, and validates the URL before writing it to the cache +4. Is idempotent - safe to re-run at any time + +Cards with no image (neither explicit nor cached) display a branded gradient placeholder. diff --git a/README.md b/README.md index dc7740cc8..0b309a1b7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # Overture Documentation [![WCAG 2.2 AA](https://img.shields.io/badge/WCAG_2.2-AA-green)](https://www.w3.org/WAI/WCAG22/quickref/) +[![release-calendar.json](https://img.shields.io/badge/%F0%9F%94%97-release--calendar.json-4051CC)](https://docs.overturemaps.org/release-calendar.json) -This repository uses [Docusaurus](https://docusaurus.io/) to publish the documentation pages seen at [docs.overturemaps.org](https://docs.overturemaps.org) +This repository uses [Docusaurus](https://docusaurus.io/) to publish the documentation pages seen at [docs.overturemaps.org](https://docs.overturemaps.org). Maintainer procedures (monthly release calendar updates, schema snapshots, OG image cache) are in [CONTRIBUTING](CONTRIBUTING.md).

@@ -15,44 +16,28 @@ This repository uses [Docusaurus](https://docusaurus.io/) to publish the documen - `blog/`: Entries for the Overture engineering blog available at docs.overturemaps.org/blog - `community/`: The community page that showcases Overture data being used in the wild. - `community-projects.json` - source data for all community project cards - - `og-image-cache.json` - cached `og:image` URLs for entries without an explicit `image` field (see [OG Image Cache](#og-image-cache) below) + - `og-image-cache.json` - cached `og:image` URLs for entries without an explicit `image` field (see [CONTRIBUTING](CONTRIBUTING.md#og-image-cache)) - `docs/`: The main documentation pages available at docs.overturemaps.org/. The sidebar for these pages is manually curated in the `sidebars.js` file. -- `schema/`: Source for the schema reference overview page (`index.md`) and scratch output of the schema doc generator. See below. -- `schema_versioned_docs/`, `schema_versioned_sidebars/`, `schema_versions.json`: committed snapshots of the schema reference for each released schema tag. See below. +- `schema/`: Source for the schema reference overview page (`index.md`) and scratch output of the schema doc generator. +- `schema_versioned_docs/`, `schema_versioned_sidebars/`, `schema_versions.json`: committed snapshots of the schema reference for each released schema tag. +- `static/release-calendar.json`: the release calendar data (see [Release Calendar](#release-calendar)) ## Schema Reference (`docs.overturemaps.org/schema`) -The Overture schema repository [OvertureMaps/schema](https://github.com/OvertureMaps/schema) maintains the official Overture schema as Pydantic models, and the reference pages under `docs.overturemaps.org/schema` are generated directly from those models. +The reference pages under `docs.overturemaps.org/schema` are generated from the Pydantic models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema). Only released schema tags are published; the newest is served at `/schema/` and older ones at `/schema/vX.Y.Z/`. -The schema reference is its own [versioned Docusaurus docs instance](https://docusaurus.io/docs/versioning) (plugin id `schema`, config in `docusaurus.config.js`, sidebar in `sidebars-schema.js`), separate from the main `docs/` instance. Only released schema tags are published; there is no rolling "latest" built from `main`. The newest tag in `schema_versions.json` is served at `/schema/`, older tags at `/schema/vX.Y.Z/`, and a version dropdown appears in the navbar on schema pages only. +**If you spot a typo or error under `docs.overturemaps.org/schema`, it is not fixable in this repository.** Open an issue or PR against the docstrings/models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema) instead; the fix appears in the next release's snapshot. How snapshots are added is in [CONTRIBUTING](CONTRIBUTING.md#schema-reference). -Snapshots are generated once per tag and committed under `schema_versioned_docs/version-vX.Y.Z/`. Builds do not call the schema generator, so a production deploy only ever changes the schema pages when a new snapshot lands here. +## Release Calendar -**If you spot a typo or error under `docs.overturemaps.org/schema`, it is not fixable in this repository.** Open an issue or PR against the docstrings/models in [OvertureMaps/schema](https://github.com/OvertureMaps/schema) instead; the fix appears in the next release's snapshot. Re-snapshotting an existing tag is possible (delete its three artifacts and re-run the script below) but pointless unless the tag itself moved. +Release dates are published as JSON at `https://docs.overturemaps.org/release-calendar.json`, with a JSON Schema alongside it at `release-calendar.schema.json` (referenced by the file's `$schema` key, so editors validate edits as you type). `releases` is a flat list, and each entry has: -The overview page (`schema/index.md`) is copied into each snapshot when it's created. Edits to it need to be applied to the `index.md` in each `schema_versioned_docs/version-*/` too. +- `date`: release date, ISO 8601 +- `dataVersion`: the release's data version +- `schemaVersion`: the schema version, or `null` when not yet determined (renders as TBD) +- `majorChangeMonth`: optional, `true` for the quarterly major breaking change release -### Adding a schema version - -Run this after a `vX.Y.Z` tag is published in [OvertureMaps/schema](https://github.com/OvertureMaps/schema/releases). It needs `git`, [`uv`](https://docs.astral.sh/uv/), and `npm install` already done. - -```shell -npm run add-schema-version -- v2.0.0 -``` - -The script (`scripts/add-schema-version.mjs`) clones the schema repo at that tag, runs its `overture-codegen` into `schema/reference/`, then runs `docusaurus docs:version:schema `, which writes: - -- `schema_versioned_docs/version-/` (with links into the schema repo pinned to the tag) -- `schema_versioned_sidebars/version--sidebars.json` -- an entry in `schema_versions.json` (kept sorted newest-first; the first entry is what `/schema/` serves) - -Commit those three and open a PR. `schema/reference/` is cleaned up afterwards. - -Only tags that ship the `overture-schema-codegen` package (v1.17.0 and later) can be added; earlier releases were JSON Schema and have no generator. The script refuses tags that don't match `vX.Y.Z` or are already in `schema_versions.json`. - -### Schema PR previews - -The schema repo's PR preview workflow checks out this repo, generates Markdown from the PR branch into `schema/reference/`, and builds with `SCHEMA_PREVIEW=true`. In that mode the `schema` instance builds only the `current` version from `schema/reference/` at `/schema/`; committed snapshots, the version dropdown, blog, and community pages are skipped. +An entry dated after today is upcoming, and anything else has shipped. A release dated today counts as shipped. The file has no status field, so compare `date` against the current date. For which releases have actually shipped, use [STAC](https://stac.overturemaps.org/). The `/release-calendar` page renders from this file, and the monthly update steps are in [CONTRIBUTING](CONTRIBUTING.md#release-calendar). ## Developing @@ -77,32 +62,12 @@ Now navigate to to see the live preview. - `npm run build` - Build the production site (also shows locale/translation warnings and broken link checks) - `npm run serve` - Serve the built site locally - `npm run deploy` - Deploy the site -- `npm run fetch-og` - Fetch and cache `og:image` metadata for community project entries (see [OG Image Cache](#og-image-cache) below) -- `npm run add-schema-version -- vX.Y.Z` - Snapshot the schema reference for a released schema tag (see [Adding a schema version](#adding-a-schema-version) above) +- `npm run fetch-og` - Fetch and cache `og:image` metadata for community project entries (see [CONTRIBUTING](CONTRIBUTING.md#og-image-cache)) +- `npm run add-schema-version -- vX.Y.Z` - Snapshot the schema reference for a released schema tag (see [CONTRIBUTING](CONTRIBUTING.md#adding-a-schema-version)) - `npm run swizzle` - Customize Docusaurus components by "ejecting" them for modification - `npm run write-translations` - Generate translation files for internationalization - `npm run write-heading-ids` - Auto-generate heading IDs for better linking -## OG Image Cache - -The community page displays project cards with images. Each entry in `community/community-projects.json` can include an optional `"image"` field. For entries without one, the site falls back to a cached `og:image` fetched from the project's URL. - -The cache lives in `community/og-image-cache.json` and is committed to the repository so CI builds never make external HTTP requests. - -**When to run it:** after adding or updating entries in `community-projects.json`. - -```shell -npm run fetch-og -``` - -The script (`scripts/fetch-og-images.mjs`): -1. Skips entries that already have an explicit `"image"` field -2. Re-validates any previously cached non-empty URLs via a HEAD request (`Content-Type: image/*`) and clears invalid ones -3. Fetches the HTML for uncached entries, extracts `og:image`, and validates the URL before writing it to the cache -4. Is idempotent - safe to re-run at any time - -Cards with no image (neither explicit nor cached) display a branded gradient placeholder. - ## LLM-Friendly Content Each production build generates [llmstxt.org](https://llmstxt.org)-standard files for use with LLMs and AI tools: diff --git a/blog/2024/2024-07-22.0.mdx b/blog/2024-07-22-release-notes.mdx similarity index 99% rename from blog/2024/2024-07-22.0.mdx rename to blog/2024-07-22-release-notes.mdx index 30251af07..68982995e 100644 --- a/blog/2024/2024-07-22.0.mdx +++ b/blog/2024-07-22-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-07-22.0 release notes -slug: 2024-07-22.0 tags: - releases - addresses diff --git a/blog/2024/2024-08-20.0.mdx b/blog/2024-08-20-release-notes.mdx similarity index 99% rename from blog/2024/2024-08-20.0.mdx rename to blog/2024-08-20-release-notes.mdx index cdb8fdf25..b04c5d6e5 100644 --- a/blog/2024/2024-08-20.0.mdx +++ b/blog/2024-08-20-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-08-20.0 release notes -slug: 2024-08-20.0 tags: - releases --- diff --git a/blog/2024/2024-09-18.0.mdx b/blog/2024-09-18-release-notes.mdx similarity index 99% rename from blog/2024/2024-09-18.0.mdx rename to blog/2024-09-18-release-notes.mdx index 518d4d9f8..6cf84a2bd 100644 --- a/blog/2024/2024-09-18.0.mdx +++ b/blog/2024-09-18-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-09-18.0 release notes -slug: 2024-09-18.0 tags: - releases --- diff --git a/blog/2024/2024-10-23.0.mdx b/blog/2024-10-23-release-notes.mdx similarity index 96% rename from blog/2024/2024-10-23.0.mdx rename to blog/2024-10-23-release-notes.mdx index f77af1dbc..d9fc36150 100644 --- a/blog/2024/2024-10-23.0.mdx +++ b/blog/2024-10-23-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-10-23.0 release notes -slug: 2024-10-23.0 tags: - releases --- @@ -39,7 +38,7 @@ We removed the `connector_ids` property from the schema and replaced it with a n ## Deprecations -In the `2024-08-20.0` [release notes](https://docs.overturemaps.org/blog/2024-08-20.0/), we announced the deprecation of the `connector_ids` property in the transportation schema. We have removed that property in this release. +In the `2024-08-20.0` [release notes](https://docs.overturemaps.org/blog/2024/08/20/release-notes/), we announced the deprecation of the `connector_ids` property in the transportation schema. We have removed that property in this release. ## Theme-specific updates diff --git a/blog/2024/2024-11-13.0.mdx b/blog/2024-11-13-release-notes.mdx similarity index 99% rename from blog/2024/2024-11-13.0.mdx rename to blog/2024-11-13-release-notes.mdx index 6ae004288..5ea0653f5 100644 --- a/blog/2024/2024-11-13.0.mdx +++ b/blog/2024-11-13-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-11-13.0 release notes -slug: 2024-11-13.0 tags: - releases --- diff --git a/blog/2024/2024-12-18.0.mdx b/blog/2024-12-18-release-notes.mdx similarity index 99% rename from blog/2024/2024-12-18.0.mdx rename to blog/2024-12-18-release-notes.mdx index ad29c9e99..f62d8f1f8 100644 --- a/blog/2024/2024-12-18.0.mdx +++ b/blog/2024-12-18-release-notes.mdx @@ -1,6 +1,5 @@ --- title: 2024-12-18.0 release notes -slug: 2024-12-18.0 tags: - releases --- diff --git a/docs/examples/ibis.mdx b/docs/examples/ibis.mdx index 33a0580eb..768a44e39 100644 --- a/docs/examples/ibis.mdx +++ b/docs/examples/ibis.mdx @@ -34,7 +34,7 @@ import ibis from ibis import _ t = ibis.read_parquet( - "s3://overturemaps-us-west-2/release/2024-09-18.0/theme=base/type=infrastructure/*", + "s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=infrastructure/*", table_name="infra", ) diff --git a/docs/examples/pandas.mdx b/docs/examples/pandas.mdx index 838eabf13..9cd1c1a17 100644 --- a/docs/examples/pandas.mdx +++ b/docs/examples/pandas.mdx @@ -76,7 +76,7 @@ SELECT names.primary AS primary_name, ST_AsText(geometry) as geometry FROM - read_parquet('s3://overturemaps-us-west-2/release/2024-09-18.0/theme=base/type=water/*', filename=true, hive_partitioning=1) + read_parquet('s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=base/type=water/*', filename=true, hive_partitioning=1) WHERE bbox.xmin >= -91.3994 and bbox.xmax <= -89.3864 diff --git a/docs/examples/spark.mdx b/docs/examples/spark.mdx index a73a5aac0..4e014d6aa 100644 --- a/docs/examples/spark.mdx +++ b/docs/examples/spark.mdx @@ -49,7 +49,7 @@ from pyspark.sql import SparkSession spark = SparkSession.builder.getOrCreate() # Define constants for our read -OVERTURE_RELEASE = "2025-01-22.0" +OVERTURE_RELEASE = "__OVERTURE_RELEASE" COUNTRY_CODES_OF_INTEREST = ["US", "GH"] SOURCE_DATA_URL = f"s3a://overturemaps-us-west-2/release/{OVERTURE_RELEASE}/theme=places/type=place" OUTPUT_FILE = "my_super_cool_data.parquet" diff --git a/docs/examples/wherobots.mdx b/docs/examples/wherobots.mdx index f0cef9953..2d0d2c9be 100644 --- a/docs/examples/wherobots.mdx +++ b/docs/examples/wherobots.mdx @@ -148,7 +148,7 @@ Define your area of interest (in this case, Golden Gate Park) and a reusable hel region_wkt = "POLYGON ((-122.5106 37.7736, -122.4549 37.7788, -122.4491 37.7656, -122.5103 37.7606, -122.5106 37.7736))" # Define the release version as a variable for configurability -RELEASE_VERSION = "2025-06-25.0" # Update this value when a new release is available +RELEASE_VERSION = "__OVERTURE_RELEASE" def process_overture_layer(theme, type, region_wkt): """ diff --git a/docs/gers/gers-tutorial.mdx b/docs/gers/gers-tutorial.mdx index 3d5546aea..253e10fc5 100644 --- a/docs/gers/gers-tutorial.mdx +++ b/docs/gers/gers-tutorial.mdx @@ -182,7 +182,7 @@ D CREATE TABLE IF NOT EXISTS places AS confidence FROM ( SELECT * - FROM read_parquet('s3://overturemaps-us-west-2/release/2025-04-23.0/theme=places/type=place/*', filename=true, hive_partitioning=1), + FROM read_parquet('s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=places/type=place/*', filename=true, hive_partitioning=1), bounding_box WHERE addresses[1] IS NOT NULL AND bbox.xmin BETWEEN (bounding_box.min_lon - 0.01) AND (bounding_box.max_lon + 0.01) @@ -196,7 +196,7 @@ We’re doing several things here that are worth breaking down: 2. Our following `SELECT` statement prepares the Places data to more closely align with the conventions of our inspections data: the `addresses` column is broken down into component columns and we use only the primary name from the `names` column and label it to match `Facility_Name`. 3. Finally, we obtain the data from the Overture S3 bucket by remotely reading the parquet. A `WHERE` statement limits our request to a slightly buffered bounding box (buffered to ensure we’re capturing places near those facilities on the edges of our dataset). -We now have three tables: `inspections` with 27,515 records, `facilities` with 4,340 records, and `places` with 73,985 records. +We now have three tables: `inspections` with 27,515 records, `facilities` with 4,340 records, and `places` with 73,985 records. These counts, and the match results below, come from the April 2025 release. Expect different numbers when you run this against current data. Before we work on connecting them, we’ll add some spatial indexes to each table, making our lookups much faster: @@ -471,7 +471,7 @@ D CREATE TABLE places AS categories FROM ( SELECT * - FROM read_parquet('s3://overturemaps-us-west-2/release/2025-04-23.0/theme=places/type=place/*', filename=true, hive_partitioning=1), + FROM read_parquet('s3://overturemaps-us-west-2/release/__OVERTURE_RELEASE/theme=places/type=place/*', filename=true, hive_partitioning=1), bounding_box WHERE addresses[1] IS NOT NULL AND bbox.xmin BETWEEN (bounding_box.min_lon - 0.01) AND (bounding_box.max_lon + 0.01) AND diff --git a/docs/release-calendar.mdx b/docs/release-calendar.mdx index 2bf39f542..fdd0b5072 100644 --- a/docs/release-calendar.mdx +++ b/docs/release-calendar.mdx @@ -3,6 +3,7 @@ title: Releases --- import QueryBuilder from '@site/src/components/queryBuilder'; +import { ReleaseSchedule, ReleaseHistory } from '@site/src/components/ReleaseCalendar'; This page provides information about Overture's data and schema releases, including upcoming release dates, our versioning and schema change policies, data retention practices, and a complete history of past releases with links to release notes. @@ -14,15 +15,9 @@ The latest Overture data release is: ## Proposed release schedule -Our proposed release schedule is below. Release dates and schema versions are subject to change. +Our proposed release schedule is below. Release dates and schema versions are subject to change. The schedule is also available as JSON at [`/release-calendar.json`](/release-calendar.json). -| Date | Data version | Schema version | -| ------------------- | ------------------- | --------------------- | -| 21 October 2026 | `2026-10-21.0` | TBD | -| 18 November 2026 | `2026-11-18.0` | TBD | -| 16 December 2026\* | `2026-12-16.0` | TBD | - -\*reserved for quarterly major breaking change release + ## Versioning and schema changes @@ -56,44 +51,8 @@ Overture maintains publicly available data releases for a maximum of 60 days (tw Overture has been releasing data monthly since October 2023. Past releases are listed below. Only the last two months of releases available in our public buckets on AWS and Azure. The release notes for all past releases are available at the links below. -| Date | Data version | Schema version | -| ----------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | -| 23 September 2026 | [`2026-09-23.1`](https://docs.overturemaps.org/blog/2026/09/23/release-notes/) | [`v2.0.0`](https://github.com/OvertureMaps/schema/releases/tag/v2.0.0) | -| 19 August 2026 | [`2026-08-19.0`](https://docs.overturemaps.org/blog/2026/08/19/release-notes/) | [`v1.18.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.18.0) | -| 22 July 2026 | [`2026-07-22.0`](https://docs.overturemaps.org/blog/2026/07/22/release-notes/) | [`v1.18.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.18.0) | -| 17 June 2026 | [`2026-06-17.0`](https://docs.overturemaps.org/blog/2026/06/17/release-notes/) | [`v1.17.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.17.0) | -| 20 May 2026 | [`2026-05-20.0`](https://docs.overturemaps.org/blog/2026/05/20/release-notes/) | [`v1.17.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.17.0) | -| 15 April 2026 | [`2026-04-15.0`](https://docs.overturemaps.org/blog/2026/04/15/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) | -| 18 March 2026 | [`2026-03-18.0`](https://docs.overturemaps.org/blog/2026/03/18/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) | -| 18 February 2026 | [`2026-02-18.0`](https://docs.overturemaps.org/blog/2026/02/18/release-notes/) | [`v1.16.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.16.0) | -| 21 January 2026 | [`2026-01-21.0`](https://docs.overturemaps.org/blog/2026/01/21/release-notes/) | [`v1.15.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0) | -| 17 December 2025 | [`2025-12-17.0`](https://docs.overturemaps.org/blog/2025/12/17/release-notes/) | [`v1.15.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.15.0) | -| 19 November 2025 | [`2025-11-19.0`](https://docs.overturemaps.org/blog/2025/11/19/release-notes/) | [`v1.14.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.14.0) | -| 22 October 2025 | [`2025-10-22.0`](https://docs.overturemaps.org/blog/2025/10/22/release-notes/) | [`v1.13.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.13.0) | -| 24 September 2025 | [`2025-09-24.0`](https://docs.overturemaps.org/blog/2025/09/24/release-notes/) | [`v1.12.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.12.0) | -| 20 August 2025 | [`2025-08-20.0`](https://docs.overturemaps.org/blog/2025/08/20/release-notes/) | [`v1.11.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.11.0) | -| 23 July 2025 | [`2025-07-23.0`](https://docs.overturemaps.org/blog/2025/07/23/release-notes/) | [`v1.11.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.11.0) | -| 25 June 2025 | [`2025-06-25.0`](https://docs.overturemaps.org/blog/2025/06/25/release-notes/) | [`v1.10.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.10.0) | -| 21 May 2025 | [`2025-05-21.0`](https://docs.overturemaps.org/blog/2025/05/21/release-notes/) | [`v1.9.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.9.0) | -| 23 April 2025 | [`2025-04-23.0`](https://docs.overturemaps.org/blog/2025/04/23/release-notes/) | [`v1.8.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.8.0) | -| 20 March 2025 | [`2025-03-19.1`](https://docs.overturemaps.org/blog/2025/03/19/release-notes/) | [`v1.7.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.7.0) | -| 19 March 2025 | [`2025-03-19.0`](https://docs.overturemaps.org/blog/2025/03/19/release-notes/) | [`v1.7.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.7.0) | -| 19 February 2025 | [`2025-02-19.0`](https://docs.overturemaps.org/blog/2025/02/19/release-notes/) | [`v1.6.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.6.0) | -| 22 January 2025 | [`2025-01-22.0`](https://docs.overturemaps.org/blog/2025/01/22/release-notes/) | [`v1.5.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.5.0) | -| 18 December 2024 | [`2024-12-18.0`](https://docs.overturemaps.org/blog/2024-12-18.0/) | [`v1.4.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.4.0) | -| 13 November 2024 | [`2024-11-13.0`](https://docs.overturemaps.org/blog/2024-11-13.0/) | [`v1.3.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.3.0) | -| 23 October 2024 | [`2024-10-23.0`](https://docs.overturemaps.org/blog/2024-10-23.0/) | [`v1.2.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.2.0) | -| 18 September 2024 | [`2024-09-18.0`](https://docs.overturemaps.org/blog/2024-09-18.0/) | [`v1.1.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.1.0) | -| 20 August 2024 | [`2024-08-20.0`](https://docs.overturemaps.org/blog/2024-08-20.0/) | [`v1.1.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.1.0) | -| 22 July 2024 | [`2024-07-22.0`](https://docs.overturemaps.org/blog/2024-07-22.0/) | [`v1.0.0`](https://github.com/OvertureMaps/schema/releases/tag/v1.0.0) | -| 24 June 2024 | `2024-06-13-beta.1` | `v0.12.0-beta` | -| 13 June 2024 | `2024-06-13-beta.0` | `v0.12.0-beta` | -| 16 May 2024 | `2024-05-16-beta.0` | `v0.11.0-beta` | -| 16 April 2024 | `2024-04-16-beta.0` | `v0.10.0-beta` | -| 12 March 2024 | `2024-03-12-alpha.0` | `v0.9.0` | -| 15 February 2024 | `2024-02-15-alpha.0` | `v0.8.0` | -| 17 January 2024 | `2024-01-17-alpha.0` | `v0.7.0` | -| 14 December 2023 | `2023-12-14-alpha.0` | `v0.7.0` | -| 14 November 2023 | `2023-11-14-alpha.0` | `v0.6.0` | -| 19 October 2023 | `2023-10-19-alpha.0` | `v0.5.0` | -| 26 July 2023 | `2023-07-26-alpha.0` | `v0.4.0` | + + +## Release data as JSON + +The schedule and history above are also published as JSON at [`https://docs.overturemaps.org/release-calendar.json`](/release-calendar.json), for scripts and pipelines that need the next release date without scraping this page. The file's shape is described by its [JSON Schema](/release-calendar.schema.json). To find out which releases have shipped, use the [STAC catalog](https://stac.overturemaps.org/) instead. diff --git a/docusaurus.config.js b/docusaurus.config.js index c73c0235a..1a0e79ce1 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -4,6 +4,9 @@ const { themes } = require('prism-react-renderer'); const schemaVersions = require('./schema_versions.json'); +const { splitReleases } = require('./src/releaseCalendar'); +const releaseCalendar = require('./static/release-calendar.json'); + // both modes use the dark palette — code blocks are forced dark bg in // light mode too (see custom.css), so light-theme token colors fail contrast. const codeTheme = themes.nightOwl; @@ -23,7 +26,8 @@ function getFromEnvironment(variableName, defaultValue) { } function getLatestOvertureRelease() { - const fallback = '2026-09-23.1'; + // Used only when the STAC catalog is unreachable: the newest release in release-calendar.json. + const fallback = splitReleases(releaseCalendar.releases).shipped[0].dataVersion; try { const { execSync } = require('child_process'); const response = execSync('curl -s https://stac.overturemaps.org/catalog.json', { @@ -41,6 +45,14 @@ function getLatestOvertureRelease() { const latestOvertureRelease = getLatestOvertureRelease(); +// Dates with a release notes post (blog/YYYY-MM-DD-release-notes.mdx). The release +// history table links only to posts that exist; the blog isn't built for schema previews. +const releaseNoteDates = isSchemaPreview + ? [] + : require('fs') + .readdirSync('blog') + .flatMap((file) => /^(\d{4}-\d{2}-\d{2})-release-notes\.mdx?$/.exec(file)?.[1] ?? []); + // Schema reference docs are a separate, versioned docs instance (see README // "Schema Reference"). Only released schema tags are published: snapshots live // in schema_versioned_docs/, the newest is served at /schema/ and older ones at @@ -61,7 +73,10 @@ const schemaVersionOptions = isSchemaPreview includeCurrentVersion: false, lastVersion: latestSchemaVersion, versions: Object.fromEntries( - schemaVersions.map((v) => [v, { label: v, banner: 'none', path: v === latestSchemaVersion ? '' : v }]), + schemaVersions.map((v) => [ + v, + { label: v, banner: 'none', path: v === latestSchemaVersion ? '' : v }, + ]) ), }; @@ -73,6 +88,7 @@ const config = { customFields: { overtureRelease: latestOvertureRelease, + releaseNoteDates, pmtiles_path: 'https://tiles.overturemaps.org/' + latestOvertureRelease, }, @@ -145,6 +161,19 @@ const config = { from: '/releases', to: '/release-calendar/', }, + // Release notes posts used custom slugs (/blog//) before they + // were renamed to the standard blog/YYYY-MM-DD-release-notes.mdx. + ...[ + '2024-07-22', + '2024-08-20', + '2024-09-18', + '2024-10-23', + '2024-11-13', + '2024-12-18', + ].map((date) => ({ + from: `/blog/${date}.0`, + to: `/blog/${date.replaceAll('-', '/')}/release-notes/`, + })), { // Renamed from "Taxonomy Browser" to "Taxonomy Explorer". from: '/guides/places/taxonomy-browser', @@ -241,10 +270,10 @@ const config = { docs: { sidebar: { hideable: true, - }, }, - image: 'img/omf_logo_transparent.png', - navbar: { + }, + image: 'img/omf_logo_transparent.png', + navbar: { title: 'Overture Maps', logo: { alt: 'Overture Maps Foundation Logo', diff --git a/package-lock.json b/package-lock.json index 3ad529745..5225be0bc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -34,6 +34,7 @@ "@testing-library/dom": "^10.4.2", "@testing-library/jest-dom": "^7.0.1", "@testing-library/react": "^16.3.3", + "ajv": "^6.15.0", "eslint": "^10.11.0", "eslint-config-prettier": "^10.0.1", "eslint-plugin-react": "^7.37.4", @@ -9909,9 +9910,9 @@ } }, "node_modules/ajv": { - "version": "6.14.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", - "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", + "version": "6.15.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz", + "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==", "license": "MIT", "dependencies": { "fast-deep-equal": "^3.1.1", diff --git a/package.json b/package.json index 4cc7d62fc..5dc712a95 100644 --- a/package.json +++ b/package.json @@ -52,6 +52,7 @@ "@testing-library/dom": "^10.4.2", "@testing-library/jest-dom": "^7.0.1", "@testing-library/react": "^16.3.3", + "ajv": "^6.15.0", "eslint": "^10.11.0", "eslint-config-prettier": "^10.0.1", "eslint-plugin-react": "^7.37.4", diff --git a/src/__tests__/releaseCalendar.test.js b/src/__tests__/releaseCalendar.test.js new file mode 100644 index 000000000..5bc49f6fd --- /dev/null +++ b/src/__tests__/releaseCalendar.test.js @@ -0,0 +1,71 @@ +import { describe, it, expect } from 'vitest'; +import Ajv from 'ajv'; +import calendar from '../../static/release-calendar.json'; +import schema from '../../static/release-calendar.schema.json'; +import { splitReleases, releaseNotesPath } from '../releaseCalendar'; + +describe('splitReleases', () => { + const releases = [ + { date: '2026-11-18' }, + { date: '2026-09-23' }, + { date: '2026-10-21' }, + { date: '2026-08-19' }, + ]; + + it('orders shipped newest first and upcoming soonest first', () => { + const { shipped, upcoming } = splitReleases(releases, '2026-10-08'); + expect(shipped.map((r) => r.date)).toEqual(['2026-09-23', '2026-08-19']); + expect(upcoming.map((r) => r.date)).toEqual(['2026-10-21', '2026-11-18']); + }); + + it('treats a release dated today as shipped', () => { + const { shipped, upcoming } = splitReleases(releases, '2026-10-21'); + expect(shipped[0].date).toBe('2026-10-21'); + expect(upcoming.map((r) => r.date)).toEqual(['2026-11-18']); + }); +}); + +describe('releaseNotesPath', () => { + const dates = ['2025-03-19', '2026-09-23']; + + it('builds the blog path for a release with a post', () => { + expect(releaseNotesPath('2026-09-23.1', dates)).toBe('/blog/2026/09/23/release-notes/'); + }); + + it('maps a patch release to its base release post', () => { + expect(releaseNotesPath('2025-03-19.1', dates)).toBe('/blog/2025/03/19/release-notes/'); + }); + + it('returns null when no post exists', () => { + expect(releaseNotesPath('2026-10-21.0', dates)).toBeNull(); + expect(releaseNotesPath('2023-07-26-alpha.0', dates)).toBeNull(); + }); +}); + +describe('release-calendar.json', () => { + it('validates against its schema', () => { + const validate = new Ajv({ format: 'full' }).compile(schema); + expect(validate(calendar), JSON.stringify(validate.errors)).toBe(true); + }); + + it('rejects impossible dates', () => { + const validate = new Ajv({ format: 'full' }).compile(schema); + const bad = { + releases: [{ date: '2026-02-30', dataVersion: '2026-02-30.0', schemaVersion: null }], + }; + expect(validate(bad)).toBe(false); + }); + + it('points $schema at the published schema', () => { + expect(calendar.$schema).toBe(schema.$id); + }); + + it('has unique data versions that match their release month', () => { + const versions = calendar.releases.map((r) => r.dataVersion); + expect(new Set(versions).size).toBe(versions.length); + for (const r of calendar.releases) { + expect(r.date).toMatch(/^\d{4}-\d{2}-\d{2}$/); + expect(r.dataVersion.startsWith(r.date.slice(0, 7))).toBe(true); + } + }); +}); diff --git a/src/components/ReleaseCalendar.jsx b/src/components/ReleaseCalendar.jsx new file mode 100644 index 000000000..a5cd3ec3f --- /dev/null +++ b/src/components/ReleaseCalendar.jsx @@ -0,0 +1,80 @@ +import Link from '@docusaurus/Link'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import calendar from '@site/static/release-calendar.json'; +import { splitReleases, releaseNotesPath } from '../releaseCalendar'; + +const formatDate = (iso) => + new Date(`${iso}T00:00:00Z`).toLocaleDateString('en-GB', { + day: 'numeric', + month: 'long', + year: 'numeric', + timeZone: 'UTC', + }); + +const { shipped, upcoming } = splitReleases(calendar.releases); + +// Pre-1.0 schema tags have no release page worth linking. +const schemaLink = (v) => + /^v[1-9]\d*\.\d+\.\d+$/.test(v) + ? `https://github.com/OvertureMaps/schema/releases/tag/${v}` + : null; + +function ReleaseTable({ rows, renderVersion, renderSchema, renderDate }) { + return ( + + + + + + + + + + {rows.map((r) => ( + + + + + + ))} + +
DateData versionSchema version
{renderDate(r)}{renderVersion(r)}{renderSchema(r)}
+ ); +} + +export function ReleaseSchedule() { + return ( + <> + `${formatDate(r.date)}${r.majorChangeMonth ? '*' : ''}`} + renderVersion={(r) => {r.dataVersion}} + renderSchema={(r) => r.schemaVersion ?? 'TBD'} + /> +

*reserved for quarterly major breaking change release

+ + ); +} + +export function ReleaseHistory() { + const { + siteConfig: { customFields }, + } = useDocusaurusContext(); + + return ( + formatDate(r.date)} + renderVersion={(r) => { + const code = {r.dataVersion}; + const path = releaseNotesPath(r.dataVersion, customFields.releaseNoteDates); + return path ? {code} : code; + }} + renderSchema={(r) => { + const code = {r.schemaVersion ?? 'TBD'}; + const href = schemaLink(r.schemaVersion); + return href ? {code} : code; + }} + /> + ); +} diff --git a/src/components/queryBuilder.js b/src/components/queryBuilder.js index 5688ac1cd..49205043d 100644 --- a/src/components/queryBuilder.js +++ b/src/components/queryBuilder.js @@ -1,15 +1,6 @@ import CodeBlock from '@theme/CodeBlock'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; - -function replacePlaceholders(str, release) { - const athenaRelease = 'v' + release.replaceAll('.', '_').replaceAll('-', '_'); - const pmtilesRelease = release.split('.', 1)[0]; - - return str - .replaceAll('__ATHENA_OVERTURE_RELEASE', athenaRelease) - .replaceAll('__PMTILES_OVERTURE_RELEASE', pmtilesRelease) - .replaceAll('__OVERTURE_RELEASE', release); -} +import { replacePlaceholders } from '../releasePlaceholders'; export default function QueryBuilder(args) { const { @@ -22,7 +13,11 @@ export default function QueryBuilder(args) { if (args.href) { var href = replacePlaceholders(args.href, customFields.overtureRelease); - return {text}; + return ( + + {text} + + ); } if (args.inline) { diff --git a/src/releaseCalendar.js b/src/releaseCalendar.js new file mode 100644 index 000000000..508e52145 --- /dev/null +++ b/src/releaseCalendar.js @@ -0,0 +1,31 @@ +// CommonJS so docusaurus.config.js can require it alongside the React components. + +/** + * Splits release-calendar.json entries into shipped (newest first) and upcoming + * (soonest first). A release dated today counts as shipped. + * @param {Array<{date: string}>} releases + * @param {string} today ISO date, e.g. 2026-10-08 + */ +function splitReleases(releases, today = new Date().toISOString().slice(0, 10)) { + const byDate = (a, b) => a.date.localeCompare(b.date); + const sorted = [...releases].sort(byDate); + return { + shipped: sorted.filter((r) => r.date <= today).reverse(), + upcoming: sorted.filter((r) => r.date > today), + }; +} + +/** + * Path of a release's notes post, or null when no post exists. Posts follow + * blog/YYYY-MM-DD-release-notes.mdx, and patch releases (2025-03-19.1) share + * their base release's post. + * @param {string} dataVersion + * @param {string[]} noteDates dates (YYYY-MM-DD) that have a release notes post + */ +function releaseNotesPath(dataVersion, noteDates) { + const date = /^\d{4}-\d{2}-\d{2}/.exec(dataVersion)?.[0]; + if (!date || !noteDates.includes(date)) return null; + return `/blog/${date.replaceAll('-', '/')}/release-notes/`; +} + +module.exports = { splitReleases, releaseNotesPath }; diff --git a/src/releasePlaceholders.js b/src/releasePlaceholders.js new file mode 100644 index 000000000..6abb35c5c --- /dev/null +++ b/src/releasePlaceholders.js @@ -0,0 +1,9 @@ +export function replacePlaceholders(str, release) { + const athenaRelease = 'v' + release.replaceAll('.', '_').replaceAll('-', '_'); + const pmtilesRelease = release.split('.', 1)[0]; + + return str + .replaceAll('__ATHENA_OVERTURE_RELEASE', athenaRelease) + .replaceAll('__PMTILES_OVERTURE_RELEASE', pmtilesRelease) + .replaceAll('__OVERTURE_RELEASE', release); +} diff --git a/src/theme/CodeBlock/index.js b/src/theme/CodeBlock/index.js new file mode 100644 index 000000000..1ac6243f2 --- /dev/null +++ b/src/theme/CodeBlock/index.js @@ -0,0 +1,20 @@ +import CodeBlock from '@theme-original/CodeBlock'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import { replacePlaceholders } from '@site/src/releasePlaceholders'; + +// Resolves __OVERTURE_RELEASE and friends in plain fenced code blocks, so examples +// can use the placeholder without wrapping the block in QueryBuilder. +export default function CodeBlockWrapper(props) { + const { + siteConfig: { customFields }, + } = useDocusaurusContext(); + const { children } = props; + + return ( + + {typeof children === 'string' + ? replacePlaceholders(children, customFields.overtureRelease) + : children} + + ); +} diff --git a/static/notebooks/overture-duckdb-pandas-example.ipynb b/static/notebooks/overture-duckdb-pandas-example.ipynb index 4586c6d28..dee032af2 100644 --- a/static/notebooks/overture-duckdb-pandas-example.ipynb +++ b/static/notebooks/overture-duckdb-pandas-example.ipynb @@ -33,7 +33,13 @@ "import pandas as pd\n", "import geopandas as gpd\n", "from shapely import wkt\n", - "import duckdb" + "import duckdb\n", + "import json\n", + "from urllib.request import urlopen\n", + "\n", + "# latest Overture release, from the STAC catalog\n", + "with urlopen('https://stac.overturemaps.org/catalog.json') as response:\n", + " release = json.load(response)['latest']" ] }, { @@ -43,12 +49,9 @@ "metadata": {}, "outputs": [], "source": [ - "# install and load DuckDB extensions to work with spatial data and AWS\n", - "%sql INSTALL spatial;\n", - "%sql INSTALL httpfs;\n", - "%sql LOAD spatial;\n", - "%sql LOAD httpfs;\n", - "%sql SET s3_region='us-west-2'" + "# load (or reload) jupysql to create SQL cells\n", + "# no need to import duckdb_engine, JupySQL will auto-detect driver \n", + "%reload_ext sql" ] }, { @@ -66,10 +69,10 @@ "metadata": {}, "outputs": [], "source": [ - "# load (or reload) jupysql to create SQL cells\n", - "# no need to import duckdb_engine, JupySQL will auto-detect driver \n", - "# load (or reload) jupysql Jupyter extension to create SQL cells\n", - "%reload_ext sql" + "# configure cell output -> query to Pandas\n", + "%config SqlMagic.autopandas = True\n", + "%config SqlMagic.feedback = False\n", + "%config SqlMagic.displaycon = False" ] }, { @@ -79,10 +82,8 @@ "metadata": {}, "outputs": [], "source": [ - "# configure cell output -> query to Pandas\n", - "%config SqlMagic.autopandas = True\n", - "%config SqlMagic.feedback = False\n", - "%config SqlMagic.displaycon = False" + "# connection string\n", + "%sql duckdb:///:memory:" ] }, { @@ -92,8 +93,12 @@ "metadata": {}, "outputs": [], "source": [ - "# connection string\n", - "%sql duckdb:///:memory:" + "# install and load DuckDB extensions to work with spatial data and AWS\n", + "%sql INSTALL spatial;\n", + "%sql INSTALL httpfs;\n", + "%sql LOAD spatial;\n", + "%sql LOAD httpfs;\n", + "%sql SET s3_region='us-west-2'" ] }, { @@ -123,9 +128,9 @@ "SELECT \n", " id, \n", " names.primary AS primary_name,\n", - " ST_AsText(ST_GeomFromWKB(geometry)) as geometry\n", + " ST_AsText(geometry) as geometry\n", "FROM \n", - " read_parquet('s3://overturemaps-us-west-2/release/2024-07-22.0/theme=base/type=water/*', filename=true, hive_partitioning=1)\n", + " read_parquet('s3://overturemaps-us-west-2/release/{{release}}/theme=base/type=water/*', filename=true, hive_partitioning=1)\n", "WHERE \n", " bbox.xmin >= -91.3994\n", "\t\tand bbox.xmax <= -89.3864\n", diff --git a/static/release-calendar.json b/static/release-calendar.json new file mode 100644 index 000000000..04ae7ab5d --- /dev/null +++ b/static/release-calendar.json @@ -0,0 +1,218 @@ +{ + "$schema": "https://docs.overturemaps.org/release-calendar.schema.json", + "releases": [ + { + "date": "2023-07-26", + "dataVersion": "2023-07-26-alpha.0", + "schemaVersion": "v0.4.0" + }, + { + "date": "2023-10-19", + "dataVersion": "2023-10-19-alpha.0", + "schemaVersion": "v0.5.0" + }, + { + "date": "2023-11-14", + "dataVersion": "2023-11-14-alpha.0", + "schemaVersion": "v0.6.0" + }, + { + "date": "2023-12-14", + "dataVersion": "2023-12-14-alpha.0", + "schemaVersion": "v0.7.0" + }, + { + "date": "2024-01-17", + "dataVersion": "2024-01-17-alpha.0", + "schemaVersion": "v0.7.0" + }, + { + "date": "2024-02-15", + "dataVersion": "2024-02-15-alpha.0", + "schemaVersion": "v0.8.0" + }, + { + "date": "2024-03-12", + "dataVersion": "2024-03-12-alpha.0", + "schemaVersion": "v0.9.0" + }, + { + "date": "2024-04-16", + "dataVersion": "2024-04-16-beta.0", + "schemaVersion": "v0.10.0-beta" + }, + { + "date": "2024-05-16", + "dataVersion": "2024-05-16-beta.0", + "schemaVersion": "v0.11.0-beta" + }, + { + "date": "2024-06-13", + "dataVersion": "2024-06-13-beta.0", + "schemaVersion": "v0.12.0-beta" + }, + { + "date": "2024-06-24", + "dataVersion": "2024-06-13-beta.1", + "schemaVersion": "v0.12.0-beta" + }, + { + "date": "2024-07-22", + "dataVersion": "2024-07-22.0", + "schemaVersion": "v1.0.0" + }, + { + "date": "2024-08-20", + "dataVersion": "2024-08-20.0", + "schemaVersion": "v1.1.0" + }, + { + "date": "2024-09-18", + "dataVersion": "2024-09-18.0", + "schemaVersion": "v1.1.0" + }, + { + "date": "2024-10-23", + "dataVersion": "2024-10-23.0", + "schemaVersion": "v1.2.0" + }, + { + "date": "2024-11-13", + "dataVersion": "2024-11-13.0", + "schemaVersion": "v1.3.0" + }, + { + "date": "2024-12-18", + "dataVersion": "2024-12-18.0", + "schemaVersion": "v1.4.0" + }, + { + "date": "2025-01-22", + "dataVersion": "2025-01-22.0", + "schemaVersion": "v1.5.0" + }, + { + "date": "2025-02-19", + "dataVersion": "2025-02-19.0", + "schemaVersion": "v1.6.0" + }, + { + "date": "2025-03-19", + "dataVersion": "2025-03-19.0", + "schemaVersion": "v1.7.0" + }, + { + "date": "2025-03-20", + "dataVersion": "2025-03-19.1", + "schemaVersion": "v1.7.0" + }, + { + "date": "2025-04-23", + "dataVersion": "2025-04-23.0", + "schemaVersion": "v1.8.0" + }, + { + "date": "2025-05-21", + "dataVersion": "2025-05-21.0", + "schemaVersion": "v1.9.0" + }, + { + "date": "2025-06-25", + "dataVersion": "2025-06-25.0", + "schemaVersion": "v1.10.0" + }, + { + "date": "2025-07-23", + "dataVersion": "2025-07-23.0", + "schemaVersion": "v1.11.0" + }, + { + "date": "2025-08-20", + "dataVersion": "2025-08-20.0", + "schemaVersion": "v1.11.0" + }, + { + "date": "2025-09-24", + "dataVersion": "2025-09-24.0", + "schemaVersion": "v1.12.0" + }, + { + "date": "2025-10-22", + "dataVersion": "2025-10-22.0", + "schemaVersion": "v1.13.0" + }, + { + "date": "2025-11-19", + "dataVersion": "2025-11-19.0", + "schemaVersion": "v1.14.0" + }, + { + "date": "2025-12-17", + "dataVersion": "2025-12-17.0", + "schemaVersion": "v1.15.0" + }, + { + "date": "2026-01-21", + "dataVersion": "2026-01-21.0", + "schemaVersion": "v1.15.0" + }, + { + "date": "2026-02-18", + "dataVersion": "2026-02-18.0", + "schemaVersion": "v1.16.0" + }, + { + "date": "2026-03-18", + "dataVersion": "2026-03-18.0", + "schemaVersion": "v1.16.0" + }, + { + "date": "2026-04-15", + "dataVersion": "2026-04-15.0", + "schemaVersion": "v1.16.0" + }, + { + "date": "2026-05-20", + "dataVersion": "2026-05-20.0", + "schemaVersion": "v1.17.0" + }, + { + "date": "2026-06-17", + "dataVersion": "2026-06-17.0", + "schemaVersion": "v1.17.0" + }, + { + "date": "2026-07-22", + "dataVersion": "2026-07-22.0", + "schemaVersion": "v1.18.0" + }, + { + "date": "2026-08-19", + "dataVersion": "2026-08-19.0", + "schemaVersion": "v1.18.0" + }, + { + "date": "2026-09-23", + "dataVersion": "2026-09-23.1", + "schemaVersion": "v2.0.0" + }, + { + "date": "2026-10-21", + "dataVersion": "2026-10-21.0", + "schemaVersion": null, + "majorChangeMonth": false + }, + { + "date": "2026-11-18", + "dataVersion": "2026-11-18.0", + "schemaVersion": null, + "majorChangeMonth": false + }, + { + "date": "2026-12-16", + "dataVersion": "2026-12-16.0", + "schemaVersion": null, + "majorChangeMonth": true + } + ] +} diff --git a/static/release-calendar.schema.json b/static/release-calendar.schema.json new file mode 100644 index 000000000..fb1c1f360 --- /dev/null +++ b/static/release-calendar.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://docs.overturemaps.org/release-calendar.schema.json", + "title": "Overture release calendar", + "type": "object", + "required": ["releases"], + "additionalProperties": false, + "properties": { + "$schema": { "type": "string" }, + "releases": { + "type": "array", + "items": { "$ref": "#/definitions/release" } + } + }, + "definitions": { + "release": { + "type": "object", + "required": ["date", "dataVersion", "schemaVersion"], + "additionalProperties": false, + "properties": { + "date": { + "description": "Release date, ISO 8601.", + "type": "string", + "format": "date", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$" + }, + "dataVersion": { + "description": "Data version, e.g. 2026-10-21.0.", + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}(-(alpha|beta))?\\.\\d+$" + }, + "schemaVersion": { + "description": "Schema version, or null when not yet determined.", + "type": ["string", "null"], + "pattern": "^v\\d+\\.\\d+\\.\\d+(-(alpha|beta))?$" + }, + "majorChangeMonth": { + "description": "True when the release is reserved for quarterly major breaking changes.", + "type": "boolean" + } + } + } + } +}