Skip to content

API-TRACKING.md

Latest commit

 

History

History
173 lines (141 loc) · 9.27 KB

API-TRACKING.md

File metadata and controls

173 lines (141 loc) · 9.27 KB
Raw

API inventory and progression policy

Start with the progress dashboard and its six per-header checklists. The master plan supplies the phase exit gates. The ledger is the source of API-level progress for every future implementation batch.

Frozen scope

The target is raylib 6.0 at the revision in toolchain.json. The catalog retains:

  • Every public C function in raylib.h, raymath.h, rlgl.h, rcamera.h and rgestures.h, including standalone and conditional declarations.
  • Types and their fields, aliases, opaque resources, callbacks, enums and each enum value, numeric/color macros, and source-package/preprocessor controls.
  • Optional raymath C++ operator overloads and constants. Bend equivalents may use named functions; the behavior still needs coverage.
  • Active and documented commented-out config.h defaults/overrides. Private implementation constants below companion-header implementation boundaries are implementation details, not additional public API rows.

Stable IDs use header:kind:name; overload IDs include parameter types. Duplicate declarations across headers stay visible through related_declarations; they are counted as declarations, with a separate unique-C-function-name total. Conditional alternatives of one declaration live in variants, retaining signatures, value expressions, member declarations, conditions and source lines. Implicit enum values reference the previous enumerator rather than guessing a host-dependent numeric interpretation.

Header guards, export macros and C compatibility glue remain support entries. Their Bend mapping may be a documented package/language adaptation. They are never counted as implemented rendering functions. Internal dependencies such as stb and miniaudio are used to derive raylib behavior; their private APIs are not additional Jonlib public APIs. Separate projects such as raygui and third-party bindings/homebrew ports are not public headers of this pinned raylib release.

The target matrix comes from the pinned FAQ and CMake options. Each target's evidence must enumerate applicable OS/device/backend combinations. CPU/JS/Metal execution of headless algorithms does not verify window, browser, graphics-pipeline or audio-device behavior on those platforms.

Files and authority

File Role
api/reference.json Generated source catalog, immutable revision, per-header SHA-256 and source links
api/milestones.json Editable work packages, prerequisites, verification recipes, target policy and priority overrides
api/progress.json Editable item-level implementation, status, scope, gaps and evidence; omitted entries mean not-started
api/ledger.json Generated join: one complete planning record per catalog ID
api/summary.json Generated counts, milestone progress and next-work queue
docs/PROGRESS.md, docs/api/*.md Generated human-readable dashboard and complete checklists
docs/api-map.json Generated legacy view of implemented core mappings consumed by conformance

Every record has a current or proposed Bend surface, milestone, source contract, type/API/work-package dependencies, a verification recipe and next action. Proposed names are planning targets, not approved or implemented Bend interfaces. The first action for an unstarted API is to derive detailed acceptance from its implementation and examples; declaration enumeration alone cannot settle its edge semantics. Known API prerequisites are explicit; dependency lists may grow as each contract is investigated. Work packages are displayed in topological order. Phase labels indicate the full delivery phase; foundational slices of rlgl/shaders are required earlier by 2D/3D work.

Status and completion

  • not-started: catalogued and assigned work, no implementation established.
  • in-progress: active work, with scope/evidence recorded as available.
  • partial: a usable mapped subset with evidence and open domains/gates.
  • blocked: a concrete blocker prevents the planned implementation.
  • complete: the entire reference contract meets every completion gate.

Six gates make the master plan's criteria explicit: availability, behavior, ownership, integration, targets, performance. Ownership is tracked separately from behavior because Bend resource adaptations need their own review. complete requires all six verified, evidence for every gate, no gaps/blocker, actual Bend symbols for functions/operators, and a result for every target ID. A reference-not-supported target requires a reason and reference evidence. Language adaptations still need behavior/ownership/integration justification.

Validation checks structure, references and evidence presence; reviewers must check that the evidence actually proves the claim. A URL or existing document is not automatically proof of parity. Existing profile-covered and contract-checked statuses survive only in the legacy conformance view; both mean partial in the authoritative ledger.

Phase 1 exit measure

The strict status completes an item only with every target, which for most Phase 1 functions means Phase 7. The master plan's Phase 1 exit measure is reported alongside it by tools/api_plan.py (dashboard, api/summary.json phase1_exit): a Phase 1 function meets it when it is partial or complete, its behavior and ownership gates are verified (CI hosts' CPU and JavaScript lanes plus forced Metal), and every remaining gap starts with Targets:, Integration:, Performance: or Undefined native behavior:. Untagged gaps count as open behavior work.

Work through one batch

  1. Pick stable IDs from docs/PROGRESS.md; inspect prerequisites and source:

    python3 tools/api_plan.py show raylib:function:ImageResize

  2. Derive domain/error/resource contracts and fixtures from the pinned source and upstream examples. Record scoped work in api/progress.json; use proposed_jonlib for a planned name and jonlib for an existing mapping.

  3. Implement and run the applicable reference comparisons, ownership checks, integration examples, targets and performance measurements.

  4. Update scope, gaps, evidence and gate results following the record rules below. Case/lane counts, hashes and timings belong in gate results (.build/gates/), not in progress records. Then regenerate and check:

    python3 tools/api_plan.py build
python3 tools/check_project.py
python3 -m unittest discover -s tests -v

  5. Report the actual delta against a revision containing this ledger:

    python3 tools/api_plan.py report --since BASE_COMMIT
python3 tools/api_plan.py report --json

Each delivery report gives: stable IDs changed, before/after status and scope, new user-visible behavior, commands/cases/targets verified, unresolved gaps, milestone progress and the next dependency. New evidence counts even when an API remains partial. Never report mapped functions divided by 600 as overall parity. The release gate also requires formats, integration, performance and the complete target matrix.

Progress record rules

api/progress.json records state the contract, not the history of how it was verified:

  • scope: inputs, formats and bounds; the error and ownership model; notable reference quirks that are reproduced or deliberately rejected. No hosts, lanes, counts of tests/observations/bytes, timings, commit hashes, CI run IDs or "pending" qualification claims. Aim for 250 characters, at most 500.
  • gaps: at most six items naming missing contract domains or target areas (formats, numeric domains, ABI, platforms, performance), about 160 characters each.
  • evidence: at most twelve repository paths, led by the probe(s) and the topic page; no historical pages or run records.

python3 tools/api_plan.py check (also run by tools/check_project.py) rejects a scope over 600 characters, more than six gaps, a gap over 200 characters, more than twelve evidence paths, and any 40-hex commit hash or 9+-digit run ID in a scope, gap or blocker.

Drift and extraction verification

tools/check_project.py runs the offline generated-file/evidence gate. Conformance additionally re-extracts all six headers from the pinned checkout. Use the checkout variables defined in README.md:

python3 tools/api_plan.py check --clang-audit \
  --raylib-source "$RAYLIB_SOURCE"

The extractor retains conditional source alternatives. An independent Clang AST audit compares all public C function names and exact C++ overload signatures, active typedefs/enumerators and C++ constants; a separate line audit accounts for every public typedef/define/constexpr alternative, including ones inactive on the auditing host. Neither audit executes those APIs: they establish declaration accounting, not runtime parity, semantic contracts or platform support. Source-aware checks also compare the whole catalog, including hashes and support entries. Extraction changes must be reviewed and explicitly regenerated with sync --raylib-source PATH; checks never repair source or generated files. The api-audit gate in tools/gates.json runs this audit on both CI hosts.