# Contributing (/docs/maintainers/contributing)



## Before a PR [#before-a-pr]

Before opening a PR, confirm the following:

* **Scope** — Keep the change to one pipeline, benchmark path, runner layer, or documentation area.
* **Runtime** — Name the intended environment: runtime profile, hosted API, checkpoint-backed local run, plus any official repo provenance.
* **Assets** — Do not commit checkpoints, generated videos, local caches, credentials, or large downloaded datasets. Keep generated assets and benchmark data explicit, reproducible, and outside git.
* **Evidence** — Include commands, output paths, skipped stages, and blockers in the PR description.

## Code expectations [#code-expectations]

* **Python** — Keep imports lazy when a model or benchmark has heavy optional dependencies.
* **Public entry points** — Put user-facing runtime classes under `worldfoundry/pipelines/` or evaluation runners under `worldfoundry/evaluation/`.
* **Model runtimes** — Implement runtime integrations under `worldfoundry/synthesis/**` in-tree. Do not depend on machine-local external checkouts; record external repos/checkpoints only as provenance or acquisition metadata until ported or vendor-reviewed.
* **Vendored code** — Treat reviewed `thirdparty/` code as isolated code. Preserve upstream license notes.
* **Synthesis** — Keep `worldfoundry/synthesis/**` infer-only: runtime wrappers, model code needed at inference time, checkpoint/path helpers, and minimal runtime configs. Do not add training launchers, dataset builders, demo media, notebooks, or generated outputs. Use `worldfoundry/data/test_cases/` for demo assets.
* **Formatting** — Avoid large unrelated formatting changes. Do not rewrite generated or vendored files unless the task requires it.
* **Naming** — Prefer canonical ids and direct runner paths; when a public name changes, document the migration instead of adding long-lived compatibility maps.

## Test placement [#test-placement]

Match tests to the surface you changed:

* **Runner, scorecard, tasks, registry** — Focused tests in `test/eval_core`.
* **Single pipeline run** — Existing scripts under `test/` or a focused validation script.
* **Stateful or interactive pipeline** — `test_stream/` or a documented stream command.
* **Benchmark runner** — Runner execution plus `zoo benchmark-run --mode official-validation` with official-shaped result files when normalizer review is needed.
* **Model runner** — Resolver/manifest validation plus a clear skipped path for missing checkpoint or credentials.

## Docs expectations [#docs-expectations]

Fumadocs is the only maintained documentation surface. Add or update paired English and Chinese pages under `docs/fumadocs/content/docs`.

When you change behavior, update the page that owns it:

* **New model or runtime profile** — `guides/supported-models`, `reference/environments`, and the model guide if behavior changes.
* **New benchmark** — `evaluation/benchmark-hub/<benchmark-id>`, the benchmark guide, and maintainer architecture pages when internals change.
* **CLI or output schema** — `reference/cli` and architecture pages that own the changed behavior.
* **Internal workflow** — `maintainers/architecture` (especially workflow and evaluation-core).

## Local validation [#local-validation]

```bash
bash scripts/setup/conda_install.sh --preset slim --env-name worldfoundry
make lint
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" python -m pytest test/eval_core -q
cd docs/fumadocs && npm run types:check && npm run build
```

For model/profile audits:

```bash
worldfoundry-eval run --all-benchmarks --plan-only \
  --output-dir tmp/worldfoundry_plan_matrix \
  --json
worldfoundry-eval validate-artifact tmp/worldfoundry_plan_matrix/suite_manifest.json \
  --kind suite-manifest \
  --strict \
  --json
```

For staged zoo validation:

```bash
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo models --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval zoo benchmarks --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval run --all-benchmarks --plan-only --output-dir tmp/worldfoundry_plan_matrix --json
conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" worldfoundry-eval validate-artifact tmp/worldfoundry_plan_matrix/suite_manifest.json --kind suite-manifest --strict --json
```

## PR evidence template [#pr-evidence-template]

```md
## Scope
- Changed:
- Not changed:

## Evidence
- Command:
- Output:
- Scorecard/report:
- Skipped stages:
- Blockers:

## Docs
- English page:
- Chinese page:
```

<Callout title="Review rule">
  A PR can add planned or source-verified entries without runnable support. It must not claim demo parity, checkpoint parity, or benchmark readiness without matching fresh evidence.
</Callout>