Contributing and releases

Building and testing a change

make rebuild     # Linux; or .\build-windows.ps1 -Target rebuild on Windows
make test        # consumer, parser, and CLI process-level tests

See Getting started for the full dependency and target list. There is no separate bootstrap step beyond a C11 gcc and GNU make — no package manager install is required to build the core library and CLI.

Before proposing a change to cli/, skim CLI-004/CLI-005: new commands go through a registry change with behavior, options, output schema, and tests together — not a speculative entry that only partially works. cli/cli_registry.c is the single source polycall --help and this documentation's CLI reference both derive from; keep it authoritative rather than adding a second command table somewhere.

Documentation

This site's source lives in site-docs/ (MkDocs docs_dir) and is built with mkdocs.yml at the repository root — deliberately kept separate from the pre-existing docs/ directory (legacy material, and the ten LPV1 standards this site summarizes but does not duplicate).

To build and preview the site locally:

pip install -r requirements-docs.txt
mkdocs serve       # live-reloading preview at http://127.0.0.1:8000
mkdocs build --strict   # what CI runs; fails on broken nav/file references

If you edit or add a page: update nav: in mkdocs.yml, keep filenames lowercase kebab-case, and prefer linking to a GitHub source file over duplicating its content when documenting one of the ten LPV1 specs (see Standardization) — that avoids the two copies drifting apart.

Every claim of the form "verified" or "tested" on this site should mean someone actually ran the command against a real build in the same or a prior session, not that it merely looks plausible. If you find a page claiming something that no longer holds (an example command that changed, a fixed bug whose caveat is now stale), correct the claim in the same change that changes the behavior — don't let documentation drift the way the pre-standardization README did.

Compatibility policy

ABI major version 1, the wire protocol version, and the Polycallfile schema version are tracked and reported together by polycall version show (see CLI reference) — a mismatch between what a build reports and what a consumer or provider was written against is a real compatibility problem, not just a cosmetic version-string difference. ABI-018 states the target policy: ABI major 1 stays stable through compatible 1.x releases; removing a public symbol, changing a signature, or changing ownership semantics requires an ABI transition, not a silent point release. This target policy is not yet backed by an automated compat-check job in this repository — verify manually against the header and the C library and ABI page when in doubt.

Do not assume a future language runtime upgrade (a new Python or Node major version, for example) is automatically compatible just because today's example works — the wire protocol and the C ABI are the compatibility boundary; a language runtime upgrade is only as safe as whatever binding code you're running against that boundary.

Releases

License: this project uses its own OBINexus "Use It, Respect It" license (see LICENSE in the repository root) — not a standard OSI template. Read it directly rather than assuming MIT/Apache/BSD terms.

A release should be able to point at, for each claim in this documentation, either a checked-in test that exercises it (tests/cli/test_cli_process.c, the parser fixtures, or a documented manual verification like this session's) or an explicit "proposed, not implemented" label — that's the same discipline docs/standards/requirement-matrix.json applies internally, just visible to readers of this site too.