Contributing

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

• 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

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

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

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:

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:

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

## Scope
- Changed:
- Not changed:

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

## Docs
- English page:
- Chinese page: