proto: ADR 0014 — versioning a generated-binding break with an unchanged wire
Records the rule 1.4.0 applied, so the next generated-binding retype cites it
instead of relitigating README rule 4's "retype → major + ADR" from scratch.
The rule: VERSION tracks the wire protocol, not any binding's API or ABI. A
change that leaves the wire byte-identical but breaks a generated binding's
source API (a C++ virtual's return type, a struct name) is a minor bump plus
a migration note — major would make session.hello refuse a client whose wire
behaviour is unchanged, which is worse than the problem. An ADR is still
required when the change encodes a design decision; "only one lane consumes
it" is not a reason to skip that, since GUI already links velox::proto and
the next such change starts with more than one consumer.
Rule 4 in contracts/README.md now points here so its "major + ADR" line
isn't read in isolation. proto-answers-daemon-m1.md's P1 writeup references
it as the durable home for the reasoning that was otherwise only in a commit
message.
Also names the nlohmann brace-init hazard the 1.4.0 work hit: json{nullptr}
is the array [null], not JSON null, so HandlerError::data is `= nullptr`. The
kind of thing a regeneration reintroduces; caught here only by an end-to-end
assertion on dispatch() output, which is called out to keep.
Docs only — no schema, VERSION, or generated-code change.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
@@ -64,6 +64,10 @@ subset, `fixtures/` documents the fixture shape and the placeholder rules.
|
||||
renaming, retyping, or changing a default → **major** bump and a written migration note
|
||||
in `docs/adr/`. `session.hello` rejects a major mismatch with error `-32001` and a
|
||||
message the GUI renders as "Velox needs updating".
|
||||
"Retype → major" is about the **wire** — a field a client parses off the socket. A
|
||||
change that leaves the wire byte-identical but breaks a *generated binding's* source
|
||||
API (a C++ virtual's return type, a struct name) is a **minor** bump plus a migration
|
||||
note — see `docs/adr/0014-generated-binding-changes-and-versioning.md`.
|
||||
5. **Changes arrive as a PR to `contracts/` alone**, containing: schema edit + fixtures +
|
||||
regenerated code + `VERSION` bump. Lanes rebase onto it. This is the only synchronization
|
||||
point in the whole project — keep it cheap and frequent rather than big and rare.
|
||||
|
||||
@@ -56,12 +56,16 @@ reason.)
|
||||
`Result` → `HandlerResult` automatically; `conformance_main.cpp` only ever inspects
|
||||
`dispatch()`'s JSON output and needed no change.
|
||||
|
||||
**Version:** minor, 1.3.0 → 1.4.0. The wire is byte-identical — no schema, fixture, or
|
||||
OpenRPC change — but every implementer of `Dispatcher` must swap `Result` → `HandlerResult`
|
||||
on their `on_*` overrides or they won't compile, and a version bump is how lanes are told
|
||||
to regenerate and adapt. Not major and not an ADR: one lane consumes this binding, it's
|
||||
the lane that asked, and there's no contested design here — the shape is the one you
|
||||
proposed. `kProtocolVersion` moves to `"1.4.0"` with it.
|
||||
**Version:** minor, 1.3.0 → 1.4.0. The wire is byte-identical — no schema, fixture,
|
||||
or OpenRPC change — but every implementer of `Dispatcher` must swap `Result` →
|
||||
`HandlerResult` on their `on_*` overrides or they won't compile, and a version bump is
|
||||
how lanes are told to regenerate and adapt. Minor, not major: a major would make
|
||||
`session.hello` refuse a client whose wire behaviour is unchanged. The rule — a
|
||||
generated-binding API break with an unchanged wire is minor + migration note, because
|
||||
`VERSION` is the protocol version, not the C++ ABI — is written up as
|
||||
`docs/adr/0014-generated-binding-changes-and-versioning.md` (this instance is
|
||||
mechanical; the ADR records the rule for the next one, which GUI will also consume
|
||||
since it already links `velox::proto`). `kProtocolVersion` moves to `"1.4.0"` with it.
|
||||
|
||||
## P2 — clarifications
|
||||
|
||||
|
||||
Reference in New Issue
Block a user