# Versioned documentation

This page was built for version **{{ VERSION }}** — 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 | {{ VERSION }} | Version of the installed Python package (`pip show edri`) |
| Git tag | {{ VERSION }} | Corresponding source release tag |
| Docs path | {{ VERSION }} | 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`:

```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.