docs: align the library ABI claim - #1655
Conversation
The library section still named ABI v21 and 46 exports. The public header now defines ABI v23 and declares 49 API entries. Remove the brittle export count and direct readers to the header. Refs mudler#342 FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: Codex:gpt-5.4 [Codex]
|
Reviewed at head
Dropping the count rather than correcting it is the right call. A live count of one file stored inside another is a drift lock: it goes stale on any ABI addition and couples an unrelated PR to a line it does not own. Pointing the reader at the header is the fix. Two notes on landing it. The trailer red is stale.
This is a structural gap rather than anything you did wrong. Widening the checker to fix this PR is not something to do inside this PR — it is a semantic checker change and needs its own row, spec, and red-before test. I would rather not merge red, so this needs a maintainer call on which way to go: add Flagging it for @mudler. The content here is correct and I would like it to land — it is only the gate ordering that is in the way. |
|
Correcting a number in my review above: I wrote that the header declares "51 Restricted to declaration lines the header has 47 The ABI version half is unaffected and is the real staleness: This weakens one argument and leaves the other standing. "The count is badly wrong" is not the case for deleting it — "a live count of one file stored inside another goes stale on any ABI addition, and couples unrelated pull requests to a line they do not own" is, and that is the argument this PR already makes. Removing the count is still the right call. |
… source, so an ABI bump can repair the README claim it invalidates (#1690) (#1693) fix(DOC-README-ABI-LANDING-SOURCE): admit include/vllm.h as a landing source, so an ABI bump can repair the README claim it invalidates (#1690) The README's `## Use it as a library (C API)` block quotes `VLLM_ABI_VERSION` straight out of `include/vllm.h`. The header was already a `USER_USAGE_FILES` member, so bumping the ABI owed `docs/USAGE.md` -- but it was not a landing source, and the README rule refuses a claim change that no landing source accompanies. The claim could therefore be invalidated by an edit to the header and never repaired by one. That is not a hypothetical: the README sits at `VLLM_ABI_VERSION 21` against a header reading `23`, and #1655 exists because no legal change could fix it. The set's own criterion already admitted the file. The checker's comment says every member is "something the README QUOTES" -- the mission, the build entry point, the demo numbers, the two example mains. The C ABI header is that same relation, and it was the only such source missing. This is a widening, so it is bounded deliberately. It admits one file and not `include/` as a class, and it permits without demanding: an ordinary ABI change still owes only `docs/USAGE.md`. `test_the_c_abi_header_is_a_landing_source` reds before the change and passes after; `test_the_c_abi_header_permits_but_does_not_demand_readme` pins that no new README obligation appears; and the three properties already pinned -- a co-edited public projection, an ordinary page under `docs/`, and the bare README -- stay red as before. 80 tests, all green. The README's other stale figure, "46 exported functions", is stale by one and not by six: the header declares 47. An earlier review of #1655 put it at 51 or 52, which swept in the four lines of the `#define VLLM_API` visibility block and counted `vllm_*` identifiers that are typedefs and struct fields rather than exported functions. Recorded here because that count is the weaker half of the argument for deleting it, and the record should not overstate it. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: AGENT:claude-opus-5 [Claude Code] Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
`origin/main` moved five commits: #1707 (one decline is one count), #1655 (the library ABI claim), #1693 (README ABI landing source), #1630 (Tenstorrent host-free decode by default) and #1687 (the Qwen3.8-27B FP8-block preconditions). None touches the multimodal limits, the model-registry seam or either tower loader, and the merge is clean. The L4 clash did NOT recur: main's `specs/multimodal-track.md` is unchanged since the previous merge, so the resolution from that merge stands untouched. Both bullets rechecked byte-for-byte rather than assumed — the L3 block still hashes `ce576508b1dfd42e` and the L4 bullet still hashes `5fe114c2c0f6e335`, matching main exactly, and the file still carries exactly one `## Owed`. The split docs were re-grepped, because they are main's files and main edits them fast. Neither `docs/guides/multimodal-input.md` nor `docs/reference/server.md` has re-acquired the "frees no memory" or "does not skip tower construction" claim this row makes false, and all four corrected surfaces survive. This merge touched only `docs/FEATURES.md`, on the Tenstorrent row, and left this row's own row intact. The index is verified by the same six checks: 622 base lines all present byte-for-byte and in order, main's 6 new rows present, this branch's 2 present, no line from neither side, no duplicated row id. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: AGENT:claude-opus-5 [claude-code]
2 participants
Row
DOCS-README-ABI-ALIGNMENT- docs-only correction, with no area-matrix lifecycle change.Before starting
scripts/ready-for-helper.pyresult when applicable: not applicable because no feature or lifecycle state moves; the staged preflight reportsready-for-helperOK.include/vllm.h:329definesVLLM_ABI_VERSION 23; the header carries 47VLLM_APIdeclaration lines, declaring 47 distinctvllm_*entry points;README.md:182already names ABI v23;README.md:385still named ABI v21 and 46 exports.What changed
Correct the library section to ABI v23 and remove the export count. The count becomes stale whenever the public C surface grows, so the README now tells readers to check the installed header.
Evidence
scripts/agent-preflight.shpasses. All documentation and record gates pass, but the full preflight has two environment or baseline failures: workflow validation requires unavailable PyYAML, and test-registration configuration aborts in unchanged code.python3 scripts/check-readme-structure.py: OKpython3 scripts/check-supported-models.py: exactly 40 registered architecturespython3 scripts/check-public-doc-tables.py: OKpython3 scripts/check-model-checklist.py: OKpython3 -m unittest tests.scripts.test_check_readme_structure tests.scripts.test_check_supported_models: 34 tests passThe broader public-doc mutation run has two pre-existing failures in untouched pages:
docs/FEATURES.mdhas 20 paragraphs against an expected 21, and a retired-claim mutation no longer matches itsdocs/STATUS.mdanchor.Speed claims
Honest gaps
No GPU test ran because this is a source-grounded README correction on a host without a usable GPU. The PR does not add a News item because it introduces no feature or benchmark result.
Why this lands with
documentation-checkpointredcheck-doc-checkpoint.pyrefuses this change: it editsREADME.mdwithouttouching a landing source. The refusal is correct by the gate's letter and wrong
for this change, and the reason it is wrong is the reason the claim drifted in
the first place.
The README quotes
VLLM_ABI_VERSIONout ofinclude/vllm.h. That header was aUSER_USAGE_FILESmember, so bumping the ABI oweddocs/USAGE.md-- but it wasnot a landing source, so the same bump was forbidden from touching the README.
The claim could be invalidated by an edit to the header and never repaired by
one. It reached
21against a header reading23because no legal change couldfix it, and this pull request is refused for being the repair rather than the
breakage.
That checker gap is filed as #1690 and fixed on
main:include/vllm.his nowa landing source, red-before/green-after pinned by
test_the_c_abi_header_is_a_landing_source, withtest_the_c_abi_header_permits_but_does_not_demand_readmeproving no new READMEobligation appears. From here a future ABI bump can carry its own README
correction and this trap does not recur.
That fix does not retroactively clear THIS change, because this one touches only
README.md-- there is no ABI edit to accompany it, and manufacturing one tosatisfy the gate would be gaming it. So this lands as an argued exception, which
is where the project puts exceptions: in the commit message, with the diff, the
author and the date, rather than in a waiver registry that can drift from the
tree. The gate is not weakened and no assertion is deleted; one commit is
knowingly landed against it, and the reason is here.
Scope of what is being waived: one README paragraph, no product code, no test,
no measurement. Every other gate on this change is green.
Correction to the anchors above
An earlier review comment on this pull request put the header at "51
VLLM_APIlines / 52 distinct
vllm_*entry points", and the body above said 49. Both aremiscounts -- 51 sweeps in the four lines of the
#define VLLM_APIvisibilityblock, and 52 counts
vllm_*identifiers anywhere in the header, includingtypedefs and struct fields that are not exported functions. The header declares
47. So the README's "46 exported functions" was stale by one, not by six.
This weakens one argument for the change and leaves the other standing. The case
for deleting the count is not that it is badly wrong; it is that a live count of
one file stored inside another goes stale on any ABI addition and couples
unrelated pull requests to a line they do not own. The ABI version half is
untouched by the correction and is the real staleness:
21against23.FOLLOWING_AGENTS_PROTOCOL
Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: Codex:gpt-5.4 [Codex]