0005. Promise source compatibility, check it against the last tag¶
- Status: Accepted
- Date: 2026-11-14
- Deciders: Sebastien Rousseau (suite alignment program, ships in 0.0.88)
Context¶
The suite's other SDKs check their public API against the last release (gorelease, japicmp, cargo-semver-checks, ApiCompat). C++ has two separate questions: does code that compiled against the old header still compile (source compatibility), and does a binary built against the old library still link and run against the new one (ABI compatibility).
The public header exposes std::string, std::optional,
std::function, std::vector and nlohmann::json in its structs. Their
layout depends on the standard library, its ABI flags and the
nlohmann/json version the caller builds with. The SDK is consumed as
source (FetchContent, add_subdirectory) or as a static library built
by the caller's own toolchain; no prebuilt shared library is published.
Options considered¶
- No check, a written N/A.
- Promise ABI stability and check it. Adding a field to a struct, as
0.0.88 does to
HttpResponseandClientOptions, would be a break, and pre-1.0 every additive change would need a pimpl redesign. - Promise source compatibility and check it with abi-compliance-checker
in its
-sourcemode; print the binary report without gating on it.
Decision¶
Option 3. scripts/api-check.sh <ref> builds the library at the
baseline and at the working tree as shared libraries with debug info,
dumps the public headers' symbols and types with abi-dumper and compares
them with abi-compliance-checker. A source incompatibility fails; the
binary report is informational. The CI api job runs it against the
last v* tag. Until the first tag exists it prints that and passes.
Consequences¶
- A removed or renamed function, type or field, or a changed signature, fails CI unless the changelog announces it as breaking (pre-1.0 the maintainer may still ship it, deliberately).
- Adding struct fields and functions stays possible within 0.0.x.
- Callers must rebuild against each release; the installed package's
version file (
ExactVersion) already refuses a different version. - If a prebuilt shared library is ever published, this decision is revisited (the binary report becomes the gate).