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
This commit is contained in:
Daniel Norman
2026-10-29 18:21:09 +01:00
parent 687dc7066d
commit d0b5cba95a
6 changed files with 236 additions and 31 deletions
+5 -1
View File
@@ -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
+7 -2
View File
@@ -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.
+23 -20
View File
@@ -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/<version>/` 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/<version>/` and, as a sibling,
`releases/radicle-search/<version>/` — 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/<version>
```
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 <version> >> 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 <version>"
```
7. Push for review:
6. Push for review:
```sh
git push rad HEAD:refs/patches
```
+30 -8
View File
@@ -1,6 +1,18 @@
#!/bin/sh
set -e
usage="Usage: $0 <version> [--from-version <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
@@ -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-<commit>`. 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.
+74
View File
@@ -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.