mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-14 02:50:51 +08:00
Daniel Norman
d0b5cba95a
- 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
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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.
|