From d0b5cba95aa86582e9c343b15b14dd20e91360ee Mon Sep 17 00:00:00 2001 From: Daniel Norman Date: Thu, 8 Oct 2026 16:31:05 +0200 Subject: [PATCH] Document API compatibility and versioning - Add ADR 0001: one SemVer version for httpd, explorer supports every release from a minimum version, a 3-month guideline to drop a replaced major, expand and contract, and one API path at /api - Treat 0.y as the major before 1.0 - Track API changes in docs/api-changes.md - List API changes in httpd release notes - Take the version from the release tag, not Cargo.toml - Pass the version to the changelog script - Link the compatibility rules from the README - Point to the compat module from the backwards compatibility rules --- explorer/AGENTS.md | 6 +- explorer/README.md | 9 +- explorer/RELEASE.md | 43 ++++---- explorer/crates/radicle-httpd/build/changelog | 38 ++++++-- .../0001-expand-and-contract-api-changes.md | 97 +++++++++++++++++++ explorer/docs/api-changes.md | 74 ++++++++++++++ 6 files changed, 236 insertions(+), 31 deletions(-) create mode 100644 explorer/docs/adr/0001-expand-and-contract-api-changes.md create mode 100644 explorer/docs/api-changes.md diff --git a/explorer/AGENTS.md b/explorer/AGENTS.md index dbf1d0a1b..0ca6cd842 100644 --- a/explorer/AGENTS.md +++ b/explorer/AGENTS.md @@ -72,7 +72,11 @@ Adding or changing an API endpoint typically touches three layers: **Backwards compatibility:** Only add to the backend API — never rename or remove fields/endpoints unless explicitly deprecating. The frontend must handle older nodes gracefully: treat new API fields as optional and fall back when -they're absent. +they're absent. Put that fallback in `http-client/lib/compat.ts`, tagged with +when it can go (`Client: remove when explorer drops httpd 0.30.`). Breaking +changes go through expand and contract, see +`docs/adr/0001-expand-and-contract-api-changes.md`, and get an entry in +`docs/api-changes.md`. ## Pre-push checklist diff --git a/explorer/README.md b/explorer/README.md index b8b8e7def..e8d5c1b16 100644 --- a/explorer/README.md +++ b/explorer/README.md @@ -49,7 +49,7 @@ There are several ways to deploy the UI publicly. Here are two common options: **Add Rewrite Rules for Client-Side Routing** -The explorer is a single-page application (SPA). To ensure that all routes are +Explorer is a single-page application (SPA). To ensure that all routes are handled correctly, add a [try_files rule](try) to your web server configuration. For example: @@ -63,6 +63,11 @@ example.com { } ``` +## Front-end API compatibility + +See [ADR 0001](docs/adr/0001-expand-and-contract-api-changes.md) for information +on front-end API compatibility. + ## Configuration There are two ways to configure the UI: **at build time** and **at run time**. @@ -135,7 +140,7 @@ run `npm run deploy`. #### Node-homepage deployment -If you operate your own seed node and want the explorer to act as a dedicated +If you operate your own seed node and want explorer to act as a dedicated front-end for it (the default behaviour), put your own node first (and ideally as the only entry) in `preferredSeeds` so it is always picked as the primary seed. diff --git a/explorer/RELEASE.md b/explorer/RELEASE.md index cba6d64c6..514896630 100644 --- a/explorer/RELEASE.md +++ b/explorer/RELEASE.md @@ -2,9 +2,9 @@ `radicle-httpd` and `radicle-search` are released **together** from this workspace: a single tag, a single changelog, and one build run that produces -artifacts for both binaries. They share the same version number, bumped in -lockstep. On [files.radicle.dev][files] each binary gets its own release folder -— `releases/radicle-httpd//` and, as a sibling, +artifacts for both binaries. They share the same version number, set by the +release tag. On [files.radicle.dev][files] each binary gets its own release +folder — `releases/radicle-httpd//` and, as a sibling, `releases/radicle-search//` — so existing `radicle-httpd` download URLs are unaffected and `radicle-search` is downloaded independently. @@ -17,6 +17,16 @@ web front-end (`radicle-explorer`) is not released this way: it is deployed continuously (rolling release) and must always remain compatible with the latest `radicle-httpd`/`radicle-search` release. +## Versioning + +Versions follow [semantic versioning](https://semver.org). The version covers +the HTTP API, the CLI and the config: bump the minor version for additions, and +the major version for removals or changes. Before 1.0, `0.y` counts as the +major, so bump `0.y.z` to `0.y.(z+1)` for additions and to `0.(y+1).0` for +removals or changes. The release tag sets the version; do not change it in +`Cargo.toml`. See [ADR 0001](docs/adr/0001-expand-and-contract-api-changes.md) +for which releases explorer supports. + ## Prerequisites - Git signing configured via SSH: @@ -35,34 +45,27 @@ continuously (rolling release) and must always remain compatible with the latest git checkout -b release/httpd/ ``` -2. Bump the version in **both** crates to the same value, so the two binaries - stay coupled: - - `crates/radicle-httpd/Cargo.toml` - - `crates/radicle-search/Cargo.toml` - -3. Update lockfiles: +2. Generate changelog: ```sh - cargo build + crates/radicle-httpd/build/changelog >> CHANGELOG.md ``` -4. Generate changelog (the version is read from - `crates/radicle-httpd/Cargo.toml`): - - ```sh - crates/radicle-httpd/build/changelog >> CHANGELOG.md - ``` - -5. Edit changelog and remove irrelevant entries. Note in each entry whether a +3. Edit changelog and remove irrelevant entries. Note in each entry whether a change belongs to `radicle-httpd` or `radicle-search`. -6. Commit release: +4. Fill in the `## API changes` section from + [`docs/api-changes.md`](docs/api-changes.md). If the release bumps the major, + write the target date to drop the previous major in that file, three months + from today. + +5. Commit release: ```sh git commit -m "Release " ``` -7. Push for review: +6. Push for review: ```sh git push rad HEAD:refs/patches ``` diff --git a/explorer/crates/radicle-httpd/build/changelog b/explorer/crates/radicle-httpd/build/changelog index 5781d968a..9481bd74a 100755 --- a/explorer/crates/radicle-httpd/build/changelog +++ b/explorer/crates/radicle-httpd/build/changelog @@ -1,6 +1,18 @@ #!/bin/sh set -e +usage="Usage: $0 [--from-version ]" + +if [ $# -lt 1 ]; then + echo "$usage" >&2 + exit 1 +fi + +# Version to generate the changelog for. The release tag sets it, not +# Cargo.toml. +version="$1" +shift + # Version from which to generate the changelog. from="" @@ -17,19 +29,12 @@ while [ $# -gt 0 ]; do ;; *) echo "error: unknown argument '$1'" >&2 + echo "$usage" >&2 exit 1 ;; esac done -# Get version from Cargo.toml -version=$(grep '^version = ' "$(dirname "$0")/../Cargo.toml" | head -1 | sed 's/version = "\(.*\)"/\1/') - -if [ -z "$version" ]; then - echo "error: could not determine version from Cargo.toml" >&2 - exit 1 -fi - # Current/latest tag or HEAD current="releases/httpd/${version}" @@ -80,6 +85,23 @@ echo # shellcheck disable=SC2016 git log --pretty=format:'* `%h` **%s** *<%ae>*' "$range" -- "$exclude" +echo +echo +echo "## API changes" +echo +echo "For node operators and explorer deployments. Fill in from docs/api-changes.md." +echo +echo "### New" +echo +echo "* None." +echo +echo "### Deprecated" +echo +echo "* None. (Name each old field or path and its removal date.)" +echo +echo "### Removed" +echo +echo "* None." echo echo "## Checksums" echo diff --git a/explorer/docs/adr/0001-expand-and-contract-api-changes.md b/explorer/docs/adr/0001-expand-and-contract-api-changes.md new file mode 100644 index 000000000..64d2194f9 --- /dev/null +++ b/explorer/docs/adr/0001-expand-and-contract-api-changes.md @@ -0,0 +1,97 @@ +# 1. Expand and contract httpd API changes + +Date: 2026-10-20 + +## Status + +Accepted + +## Context + +Explorer is deployed continuously, and the public instance at radicle.network +always runs the latest version. The seeds it reads (httpd instances) upgrade on +their own schedule, so explorer often reads an older httpd. A change to a +response can break explorer on those seeds, and the operator of a seed cannot +tell why their node no longer loads. + +## Decision + +**One version.** httpd uses semantic versions. The version covers the HTTP API, +the CLI and the config. A minor release adds, and a major release removes or +changes. Before 1.0, `0.y` counts as the major, as in Cargo: a release that only +adds bumps `0.y.z` to `0.y.(z+1)`, and a release that removes or changes bumps +it to `0.(y+1).0`. + +**Supported releases.** Explorer supports every httpd release from +`minimumSupportedVersion` in `http-client/lib/compat.ts` up to the latest. This +can span more than two majors, because before 1.0 each `0.y` is a major. +Explorer warns about a node older than that. It does not warn about a version +that it cannot parse, such as `pre-release` or `nix-`. httpd does not +warn its operator at startup: it cannot know the floor of the explorer that +reads it. + +**The 3-month guideline.** Explorer aims to support a major for at least three +months after the next major replaces it. The release that bumps the major writes +this target date in `docs/api-changes.md`, the only place that holds dates. When +the date comes, check which versions the seeds run, then raise +`minimumSupportedVersion` or move the date. You may raise it sooner, when few +seeds still run that major or when a fix needs it. + +**Expand, then contract.** A breaking change ships in two steps: + +1. Expand, in a minor release: httpd adds the new fields next to the old ones, + and keeps the old ones exactly as they were. The client reads the new fields + and falls back to the old ones. +2. Contract, in a later major release: httpd removes the old fields. It may not + remove a field or path that the explorer client or the Open Graph worker + (`workers/open-graph`) still reads. + +A security fix is the one exception: it may narrow an existing field in place, +for example to stop it from sending data that an attacker can write. It must +keep the field's type, so that older clients still parse it. Its release notes +say which field changed and why. + +**One place for compatibility code.** The client turns the responses of every +supported httpd release into one shape. Version-specific code lives in +`http-client/lib/compat.ts`. A fallback to an older endpoint stays in the client +method that calls that endpoint. + +**Name the side and the version in every removal.** httpd and the client remove +their compatibility code at different times: + +- httpd stops sending the old fields in a major release after the expand. +- The client keeps its fallback until explorer drops the last httpd release + without the new fields. + +So each removal comment says which side it is on, and when it can go: + +```rust +// Compat: older clients ... Server: remove in a major release. +``` + +```ts +// Compat: older httpd ... Client: remove when explorer drops httpd 0.30. +``` + +**Track every change in one place.** `docs/api-changes.md` lists each change +with its expand release, the consumers that read it, and its pending removals. A +release fills its `## API changes` notes from this list. + +**Feature detection, not version checks.** The client learns what a seed +supports from its responses: a field that is present, or an endpoint that +answers. It never branches on the httpd version, and uses that version only to +warn about an unsupported node. + +**No version but httpd's.** httpd does not report `apiVersion`, and serves the +API at `/api`, with no version in the path. When a path moves, the client cannot +tell from a response which path a seed has. So it keeps the old path until +explorer drops the last httpd release without the new one, and httpd serves the +old path until the first major release after that. + +## Forward compatibility + +Explorer does not support httpd releases that are newer than itself, and it does +not need to. Explorer and httpd live in one repository, and a patch that changes +the API also updates the client. radicle.network deploys explorer continuously, +so it is not older than a released httpd. A self-hosted explorer should track +the latest version for the same reason. diff --git a/explorer/docs/api-changes.md b/explorer/docs/api-changes.md new file mode 100644 index 000000000..b4d459830 --- /dev/null +++ b/explorer/docs/api-changes.md @@ -0,0 +1,74 @@ +# httpd API changes + +Every breaking change to the httpd API ships in two steps, see +[ADR 0001](adr/0001-expand-and-contract-api-changes.md). Expand adds the new +shape next to the old one. Contract removes the old one later, on each side +separately. This file tracks each change from its expand release until both +sides have contracted. + +One section per change, under the httpd release that expanded it, newest first. +Each section says what the expand added and who reads it, then lists the +contract: the code each side removes, and when it may go. Delete a contract line +when its code is gone. Delete the section when its contract list is empty. A +release fills its `## API changes` notes from the sections under its heading, +and a major release from every server line. + +- **Client contract**: the explorer client (`http-client/`) and the Open Graph + worker (`workers/open-graph/`) may stop reading the old shape when explorer + drops the last httpd release without the new shape. +- **Server contract**: httpd may stop sending the old shape in a major release + after the expand. + +## Expanded in the next release (unreleased) + +### API at `/api` + +Expand: httpd serves the API at `/api`, and still serves it at `/api/v1`. Read +by the explorer client and the Open Graph worker. + +Contract: + +- Client, when explorer drops httpd 0.30: switch to `/api` in + `http-client/lib/fetcher.ts` +- Client, when explorer drops httpd 0.30: `apiBase` in + `workers/open-graph/index.js` +- Client, when explorer drops httpd 0.30: the tests that match `/api/v1` in + `tests/visual/desktop/` and `tests/e2e/` +- Server, a major release after the client lines above: the `/v1` nest in + `crates/radicle-httpd/src/api.rs` + +### Repo facts outside the project payload + +Expand: `cobs`, `releaseCount` and a qualified `defaultBranch` move out of the +project payload. The legacy `meta` (counts and `head`) stays inside it. Read by +the explorer client and the Open Graph worker. + +Contract: + +- Client, when explorer drops httpd 0.30: `legacyMetaSchema` and + `legacyRepoFields` in `http-client/lib/compat.ts` +- Client, when explorer drops httpd 0.30: `normalizeRepo` in + `workers/open-graph/index.js` +- Server, a major release: legacy `meta` and `head` in + `crates/radicle-httpd/src/api.rs` + +### Release scope + +Expand: the releases query takes `scope` (`trusted` or `untrusted`), and the +repo reports release buckets. `allAuthors` stays. Read by the explorer client. + +Contract: + +- Client, when explorer drops httpd 0.30: `legacyReleasesQuery`, + `legacyScopeReleases` and `legacyHasOtherReleases` in + `http-client/lib/compat.ts` +- Server, a major release: `allAuthors` in + `crates/radicle-httpd/src/api/query.rs` + +### Removed `apiVersion` + +httpd no longer reports `apiVersion` in the API root, and explorer no longer +checks it. Explorer warns on nodes older than `minimumSupportedVersion` in +`http-client/lib/compat.ts`, from the `version` in the API root. Released +explorers do not read `apiVersion`. This is a removal, so the next release is a +major release.