Versioned documentation

This page was built for version 2026.10.03 — use the version switcher in the sidebar to select a different version.

This site publishes one HTML build per released tag. Historical versions are never rebuilt — each tag's build is produced once, at release time, from that exact checkout.

Version scheme

EDRI uses date-based version identifiers (CalVer):

Component

Example

Meaning

Package version

2026.10.03

Version of the installed Python package (pip show edri)

Git tag

2026.10.03

Corresponding source release tag

Docs path

2026.10.03

URL path for this version's documentation

Docker image

blastycz/edri:switch@sha256:abc123...

Switch image, pinned by digest for reproducible deployments

Stability

rcN → release candidate

Prerelease; a plain date like 2026.07.02 is a stable release

URL layout

Path

Contents

/

Redirects to /stable/.

/stable/

Alias for the highest published non-prerelease version.

/changelog/

One shared changelog updated from master and at every release tag.

/YYYY.MM.DD/

A specific stable release, e.g. /2026.07.02/.

/YYYY.MM.DDrcN/

A specific prerelease tag, e.g. /2026.07.03rc1/. Never selected as stable.

/versions.json

Machine-readable manifest of all published versions (see below).

stable and the version list are maintained by the server-side publishing pipeline. Tag pipelines produce immutable per-version sites; both release tags and master also run the separate replaceable changelog deployment. Versioned builds link to the shared page and their legacy changelog.html paths redirect to it; they never overwrite the global channel themselves.

The version switcher

The Furo sidebar includes a version <select>, populated at page-load time from /versions.json:

{
  "generated_at": "2026-07-16T12:00:00Z",
  "stable": "2026.07.02",
  "versions": [
    {"id": "stable", "label": "stable (2026.07.02)", "version": "2026.07.02", "url": "/stable/", "type": "alias"},
    {"id": "2026.07.02", "label": "2026.07.02", "version": "2026.07.02", "url": "/2026.07.02/", "type": "release"},
    {"id": "2026.07.03rc1", "label": "2026.07.03rc1", "version": "2026.07.03rc1", "url": "/2026.07.03rc1/", "type": "prerelease"}
  ]
}

The manifest's url field is authoritative — the switcher never derives a base path from id alone. Note that stable is its own entry, sharing its version field with the concrete tag it currently points to — the switcher resolves "which entry is the current build" by an exact id match first, and only falls back to a version match that explicitly skips type: "alias" entries. Without that precedence, a direct visit to /2026.07.02/ could wrongly show stable selected instead of the concrete tag, depending on manifest ordering.

Selecting a different version

When the reader picks a different entry:

  1. The switcher computes the current page's path relative to the current version's base URL (e.g. guides/installation.html).

  2. It appends that relative path to the target version's url, preserving the query string and fragment unchanged.

  3. It issues a HEAD request (2s timeout) for that computed URL. If the page exists, the browser navigates there. If it doesn't (404, timeout, or a network error), the browser instead navigates to the target version's root page.

    Trade-off: this adds one extra round-trip before navigating, in exchange for never landing the reader on a broken page. Given docs readers strongly prefer "landed somewhere useful" over "the fastest possible click", this is the intended behavior, not an oversight.

The /stable/ alias

The switcher always determines "which build is this" from the version baked into the page at build time (DOCS_VERSION), never by parsing the URL — so opening a page under /stable/ still shows the concrete tag (e.g. 2026.07.02) as the selected entry, not a literal stable entry.

However, the relative-path computation for switching versions does use the actual URL prefix the browser is on. Concretely, the switcher matches location.pathname against the longest matching prefix among all version URLs in the manifest, plus /stable/ if the manifest declares one. So:

  • Opening /2026.07.02/guides/installation.html and switching to another version lands on /2026.07.03rc1/guides/installation.html (or /2026.07.03rc1/ if that page doesn't exist).

  • Opening /stable/guides/installation.html and switching to another version also lands on /2026.07.03rc1/guides/installation.html — the relative path is computed against the /stable/ prefix actually present in the URL, not against /2026.07.02/.

This is a deliberate, consistent rule (not two separate code paths): "current base" is always resolved by longest-prefix match against the real URL, while "currently selected entry" is always resolved by the build-time version. If neither the manifest nor the URL can establish a reliable current base, the switcher still renders correctly but always sends the reader to the target version's root rather than guessing a path.

Resilience

A failure to fetch or parse /versions.json (network error, HTTP error, invalid JSON, missing/empty versions, or an entry without a valid url) never breaks the page: the switcher falls back to the single <option> already present in the built HTML for the current build's own version, logs one concise message to the browser console, and does not block any other page JavaScript.