mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-14 02:50:51 +08:00
Daniel Norman
e1f7a40c63
- Rename RADICLE_VERSION to RADICLE_HTTPD_VERSION, apart from heartwood's RADICLE_VERSION - Add Unreleased sections to the changelog and API changes log, so patches add their highlights as they land - Replace the release patch with a signed tag that one delegate pushes - Stop pushing the tag from upload: the delegate who makes the tag pushes it - Remove build/changelog - Add build/prepare to rename the Unreleased sections, in POSIX sh and awk - Ask a major release to set the target date to drop the previous major - Fix the signing key setup: use the bare key that build/tag compares against
85 lines
4.7 KiB
Markdown
85 lines
4.7 KiB
Markdown
# httpd API changes
|
|
|
|
Breaking changes to the httpd API that are between expand and contract.
|
|
[ADR 0001](adr/0001-expand-and-contract-api-changes.md) has the rules.
|
|
|
|
- When a change expands, add a section under `## Unreleased`, and add its
|
|
removals to the table.
|
|
- When a release ships, build/prepare renames `## Unreleased` to its version.
|
|
When the release bumps the major, add a target date to drop the previous major
|
|
in `## Support`. Its `## API changes` notes come from its sections and from
|
|
the server removals.
|
|
- When code is removed, delete its row. When a change has no rows left, delete
|
|
its section.
|
|
|
|
## Support
|
|
|
|
Explorer supports httpd 0.28.0 and newer, set by `minimumSupportedVersion` in
|
|
`http-client/lib/compat.ts`. No target dates are set yet.
|
|
|
|
## Removals
|
|
|
|
| When | Side | Change | Remove |
|
|
| ------------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| Explorer drops httpd 0.26 | Client | Stats endpoints | `getCommitCountBySha` and `getDiffStats` in `http-client/lib/repo.ts` |
|
|
| Explorer drops httpd 0.30 | Client | API at `/api` | `/api/v1` in `http-client/lib/fetcher.ts`, `apiBase` in `workers/open-graph/index.js`, and in the tests under `tests/visual/desktop/` and `tests/e2e/` |
|
|
| Explorer drops httpd 0.30 | Client | Repo facts | `legacyMetaSchema`, `crefsPayloadSchema` and `legacyRepoFields` in `http-client/lib/compat.ts`; `normalizeRepo` in `workers/open-graph/index.js` |
|
|
| Explorer drops httpd 0.30 | Client | Release scope | `legacyReleasesQuery`, `legacyScopeReleases` and `legacyHasOtherReleases` in `http-client/lib/compat.ts` |
|
|
| Explorer drops httpd 0.30 | Client | Release support | `releasesSupported` in `http-client/lib/compat.ts` |
|
|
| Major after client switch | Server | API at `/api` | The `/v1` nest in `crates/radicle-httpd/src/api.rs` |
|
|
| A major release | Server | Repo facts | Legacy `meta` and `head` in `crates/radicle-httpd/src/api.rs` |
|
|
| A major release | Server | Release scope | `allAuthors` in `crates/radicle-httpd/src/api/query.rs` |
|
|
|
|
## Unreleased
|
|
|
|
### API at `/api`
|
|
|
|
- Added: httpd serves the API at `/api`, and still at `/api/v1`.
|
|
- Changed in place: the API root reports `path` as `/api`. The old index at
|
|
`/api`, which only linked to `/v1`, is gone. No client reads either.
|
|
- Read by: client, Open Graph worker. Both call `/api/v1` until explorer drops
|
|
httpd 0.30, because older httpd serves only that path. So httpd keeps `/v1`
|
|
until the first major release after they switch.
|
|
|
|
### Repo facts
|
|
|
|
- Added: `cobs`, with the release buckets, and a qualified `defaultBranch`,
|
|
outside the project payload. The legacy `meta` (counts and `head`) stays
|
|
inside it.
|
|
- Changed in place: `meta.releases` counts `delegate` plus `other`, not every
|
|
release object. When httpd cannot count, it leaves the field out instead of
|
|
sending 0. Older clients parse both, because the field was always optional.
|
|
- Changed in place: only `repos/:rid` sends the release buckets and
|
|
`meta.releases`. Repo lists leave both out, because counting reads every
|
|
release of each repo.
|
|
- Read by: client, Open Graph worker.
|
|
|
|
### Release scope
|
|
|
|
- Added: the releases query takes `scope` (`trusted` or `untrusted`).
|
|
`allAuthors` stays.
|
|
- Read by: client.
|
|
|
|
### Release support
|
|
|
|
- Added: `/info` reports `httpd.releases`, whether httpd was built with release
|
|
support. Without it, a repo with no release count could be a node without
|
|
releases or a count that failed.
|
|
- Read by: client. On older httpd, it reads a release count as support.
|
|
|
|
### Version
|
|
|
|
- Removed: `apiVersion` in the API root. The client no longer checks it, and
|
|
released clients do not read it.
|
|
- Added: the client reads `version` in the API root, and warns on nodes older
|
|
than `minimumSupportedVersion`.
|
|
- This is a removal, so the release bumps the major.
|
|
|
|
## 0.27.0
|
|
|
|
### Stats endpoints
|
|
|
|
- Added: `stats/commits/:sha` and `diff/:base/:oid/stats`. The client falls back
|
|
to the tree stats and the full diff.
|
|
- Read by: client.
|