DR-011.md

May 3, 2026 · View on GitHub

DR-011: ABI versioning

Status: Accepted Date: 2026-04-30 Context: v2.0 is a SOVERSION bump. The question: do we also layer in inline-namespace versioning or symbol versioning maps?

Options considered:

  1. SOVERSION only — no inline namespace, no symbol map.
  2. SOVERSION + inline namespace v2 { ... } — enables in-process v1+v2 coexistence; future v3 can layer on cleanly.
  3. SOVERSION + linker --version-script — granular per-symbol versioning; massive overhead for a C++ library.

Decision: Option 1.

Rationale: PRD already commits to a clean cutover (no v1.x branch). SOVERSION-only is what every peer C++ HTTP library does, what distro packagers expect, what we already do. Inline namespace (2) is an escape hatch for problems we've designed around with PIMPL. Symbol-versioning maps (3) is overkill for a C++ library's lifecycle.

Consequences:

  • No inline namespace in public headers.
  • v1.x is end-of-life on the day v2.0 ships; no parallel maintenance.
  • Distros package libhttpserver2-package parallel-installable with libhttpserver1 via standard SOVERSION mechanics.