Contributing¶

The LoxiLB Inference Gateway is an open-source project and contributions are welcome — whether you are fixing a typo, improving an example, or documenting a feature that isn't covered yet.

Two repositories¶

Repository	What it holds	Where to contribute
loxilb-inference-gateway	The gateway source code, REST API spec (`api/swagger.yml`), and CI scenarios (`cicd/`)	Code, API, and behavior changes
loxilbdocs-inference-gateway	This documentation site	Documentation changes

Report a bug in the gateway itself in the code repository; report a documentation problem (inaccuracy, broken link, missing content) in the docs repository.

Contributing to the docs¶

Fork the docs repository and branch from main.

Preview locally:

pip install -r requirements.txt
mkdocs serve            # http://127.0.0.1:8000

Make sure the strict build passes (this is what CI runs):

python tools/validate_examples.py
python tools/refresh_example_inventory.py --check
python tools/refresh_body_bindings.py --check
python tools/refresh_coverage_ledger.py --check
python tools/render_metrics_reference.py --check
python tools/render_schema_reference.py --check
python -m unittest discover -s tests -p 'test_*.py' -v
mkdocs build --strict

Open a pull request and fill in the template.

The full workflow and style conventions are in CONTRIBUTING.md.

Usage-example contracts¶

The example validator extracts loxicmd, curl, JSON, YAML, and PromQL from Markdown fenced blocks. It checks CLI paths, flags, and enums against frozen CLI contracts; REST methods and paths against the combined primary and supplemental Swagger contracts; inline JSON request bodies against the matching Swagger request schema; shell syntax with bash -n; JSON with jq; and YAML with yq. PromQL metric names and selector labels are checked against the frozen release-scope manifest; documented closed label enums are checked for exact selectors. File-backed management examples are bound by exact page and file reference to actual public assets and extracted jq producer commands. Linux CI recreates those inputs; deployment-owned secrets are not substituted with fixtures. The unit suite also applies deliberately broken examples and requires the validator to reject route typos, removed flags, invalid enum values, incorrect JSON field casing, missing required fields, non-existent metric families, wrong metric labels, and wrong metric enum values.

The tracked snapshots under tests/contracts/docs_examples/ make the CI check deterministic and network-independent. Maintainers can refresh them from exact local clones after reviewing an upstream contract change:

python tools/refresh_example_contracts.py \
  --gateway-repo ../loxilb-inference-gateway \
  --gateway-ref <accepted-gateway-commit> \
  --cli-repo ../loxicmd-inference-gateway \
  --cli-ref <accepted-cli-commit>
python tools/render_metrics_reference.py --write
python tools/render_schema_reference.py --write
python tools/refresh_body_bindings.py
python tools/refresh_example_inventory.py
python tools/refresh_coverage_ledger.py
python tools/refresh_example_inventory.py --check

Validate a Gateway upgrade before refreshing the snapshot¶

The Gateway contract drift workflow checks out selected Gateway and CLI refs and performs four independent gates:

regenerate the candidate contract from both Swagger files, the engine support catalog, the release-scope metric manifest, selected public scenario/workflow evidence, and the selected CLI source;
validate documented routes, request bodies, and PromQL against that candidate contract;
require every Swagger definition added since the public schema baseline to have an explicit relevance classification and generated field reference;
compare Swagger, catalog, metric-manifest, and scenario/claim evidence with the tracked contract. Any drift fails until it is reviewed.

Run the same static gate on the validation runner:

python tools/validate_gateway_docs.py \
  --gateway-repo ../loxilb-inference-gateway \
  --gateway-ref <accepted-gateway-commit> \
  --cli-repo ../loxicmd-inference-gateway \
  --cli-ref <accepted-cli-commit>

After reviewing the report and updating affected pages, refresh only the Gateway snapshot from the exact accepted commit:

python tools/refresh_example_contracts.py \
  --only gateway \
  --gateway-repo ../loxilb-inference-gateway \
  --gateway-ref <accepted-gateway-commit>

python tools/validate_examples.py
python tools/refresh_example_inventory.py --check
python tools/render_metrics_reference.py --check
python tools/render_schema_reference.py --check
python -m unittest discover -s tests -p 'test_*.py' -v

The workflow runs on relevant documentation pull requests, weekly against Gateway main with the configured CLI baseline, and on manual dispatch with selectable gateway_ref and cli_ref. It also accepts a repository_dispatch event named gateway-api-updated; a Gateway release workflow can send that event with client_payload.gateway_ref set to the immutable Gateway commit or tag and client_payload.cli_ref set to the reviewed CLI ref. The dispatch token must stay in repository secrets and must never be placed in the event payload or logs.

These checks establish static command, route, schema, metric, evidence-object, and syntax consistency. They do not execute the Linux CLI binary, send requests to a running gateway, or qualify GPU, high-availability, or production behavior.

Visual and security style¶

Follow the layout and terminology of neighboring pages. Use Mermaid for request paths, decisions, state transitions, and component relationships when it improves understanding; keep the same semantic color palette and explain the diagram in adjacent text or a table. Validate diagrams in both light and dark themes.

Public pages and diagrams must not contain personal information, private topology, credentials, internal identifiers, private registry names, or unpublished performance claims. Security and HA behavior must be traceable to the current source contract and must state operational limitations instead of implying a guarantee.

Correctness comes first¶

Every documented field, default, enum, endpoint, and runnable example must be traceable to the code repository — api/swagger.yml / api/swagger-extras.yml for the API contract, or a working cicd/ scenario for examples. If a page and the code disagree, the code wins. When a capability is partial or still on the roadmap, we say so with a status note rather than implying it works.

Community¶

💬 Slack: loxilb.io/members
🧩 Upstream LoxiLB: github.com/loxilb-io/loxilb
🔒 Security issues: see the security policy — do not open a public issue.

By participating you agree to the project's Code of Conduct.

When updating the Gateway source baseline, regenerate both source contracts, metric/schema references and the example inventory/coverage ledger on the Linux runner. Review the recorder-derived label combinations and update the exact-source/count regression expectations with the reviewed tuple. Keep historical engine results and immutable comparison-release identities intact. Run python -m unittest discover -s tests -p 'test_*.py' -v on that runner; tests/test_metric_contracts.py includes negative enum/combination and source shape checks. Source consistency does not requalify older runtime evidence.