mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-21 22:30:41 +08:00
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:
+5
-1
@@ -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
@@ -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
@@ -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
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user