CNA-BUG-056: docs/c-api/README.md still presents the C ABI as its initial 0.1.0 library while abi.h declares 0.50.0

CNA snapshot 3b43bd86  ·  Known Issues › Current bugs  ·  source links pinned to 3b43bd86

The release gate reads its ABI label from abi.h and the old feature matrix is gone, but the C API README opens by calling the library its initial 0.1.0 shared library and then lists today's surface.

Identifier

CNA-BUG-056

Category

Bug

Subsystem

Documentation & release tooling

Status

Narrowed (partially fixed; describes only what survives)

Verified against

CNA 3b43bd86 (3b43bd8687ed46523d873f9bec4b32bd8481dcb5)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

cna_get_abi_version and the ABI identity declared in CNA/C/abi.h (CNA_ABI_VERSION_MAJOR / MINOR / PATCH), as documented under docs/c-api

Expected behaviour

The C ABI version is declared once, in CNA/C/abi.h (0.50.0 at TARGET), and ABI_VERSIONING.md, RELEASE_GATE.md and tools/c-api/abi_baseline.json agree. The product version and the C ABI version are independent, so a C API document that names an ABI version must name the current one or say that it is history.

Actual behaviour at TARGET

docs/c-api/README.md opens its Status section with “Its initial 0.1.0 shared library and public C17 headers provide ...” followed by today's surface, up to the CNB bindings. A reader comparing cna_get_abi_version's answer with the README finds 0.50.0 against 0.1.0, the product-versus-ABI confusion the versioning contract warns about.

Source locations

• docs/c-api/README.md — Status paragraph: initial 0.1.0 shared library
• modules/c-api/include/CNA/C/abi.h — CNA_ABI_VERSION_MAJOR / MINOR / PATCH = 0.50.0
• tools/c-api/check_release_gate.py — abi_version() and release_name() - the fixed half: the gate reads abi.h

Evidence

Checked by reading at 3b43bd86; not executed. Fixed since this was first reported: the release gate no longer carries a literal version. check_release_gate.py reads the three macros from abi.h (abi_version()) and refuses a release-name template without {abi_version} (release_name(), CBIND-115); the CApiReleaseGate CTest and c-api-release-gate.yml run --check. None of that reads README.md.

Narrowed at c6dec91f: bf0cde63f (2026-10-11) removed docs/c-api/FEATURE_MATRIX.md, the second document this entry named; the ABI meanwhile moved to 0.50.0. README.md is unchanged.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

CApiReleaseGate and CApiDocExportCounts (both in cmake/Tests/ModuleProbes.cmake) guard the release record and export counts; no check compares an ABI version named in docs/c-api/*.md with abi.h.

Regression test

A documentation check, next to CApiDocExportCounts, that reads the version from abi.h the way check_release_gate.py already does and fails when a docs/c-api page names a different present-tense ABI version; version-history sections may name older versions explicitly.

Blast radius

C API documentation only. The library reports 0.50.0, and the ABI baseline, release gate and versioning history are correct.

Workaround

Query cna_get_abi_version or read CNA/C/abi.h; use ABI_VERSIONING.md for the history.