# Contributing

CommonTable accepts contributions in ten bounded categories: data; mathematical modeling; optimization; agriculture and nutrition; logistics; geospatial processing; frontend and visualization; documentation; validation; and policy scenarios. Choose the narrowest relevant issue labels. A `good first issue` must be independently testable and must not require an undefined scientific judgment.

## Local setup

Install Python 3.11–3.14, uv, and Node.js 22 or later. From a fresh clone:

```bash
uv sync --frozen
npm ci
make solve
make test
make validate
```

`make web` starts the frontend. `make api` starts the optional local API. `make pages` builds the backend-free site in `.pages`. See the repository map in [README.md](README.md) and the dependency boundaries in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Test and quality commands

```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
npm run format:check
npm run lint
npm run typecheck
npm test
make regression
make validate
```

Run the full set before requesting review. The reference regression is intentionally small; do not add a national solve to pull-request CI.

## Adding geography

To add a state, copy [`templates/new-state-onboarding.json`](templates/new-state-onboarding.json), retain all 17 data-layer entries, and run `uv run python scripts/onboard_national.py --help`. State-specific environmental, agricultural, economic, and legal assumptions belong in configuration, not core-model branches.

To add a county, follow [docs/ONBOARDING_SERVICE_AREA.md](docs/ONBOARDING_SERVICE_AREA.md), add a service-area record and boundary provenance, then test parent-state reconciliation. Unavailable or suppressed values must remain unavailable; do not turn them into zero.

## Adding commodities and datasets

Use [`templates/new-commodity.yaml`](templates/new-commodity.yaml) for a commodity. Declare edible form, mass basis, nutrient and agronomic units, transformations, seasonality, losses, and substitution rules. Nutrition or agronomy review is required before a production claim.

For a new or replacement dataset, submit the data-source issue form and add a machine-readable source record. It must include source, license, version, retrieval date and method, schema, transformation steps, validation checks, geographic and temporal coverage, units, quality classification, and known limitations. Do not commit large raw downloads; use a manifest, retrieval script, public release asset, or documented external repository.

## Model, equation, and policy changes

A pull request that changes an equation, constraint, nutritional requirement, production assumption, producer-economics rule, logistics rule, or policy mechanism must contain:

1. Rationale and expected behavioral change.
2. Source, derivation, or explicit policy judgment.
3. Dimensional analysis with every unit identified.
4. Unit and property tests for the changed rule.
5. Before/after reference scenario comparison, including infeasibility if encountered.
6. Updates to methodology, assumptions, or limitations documentation.

Add a scenario definition under `packages/scenarios/definitions` for a policy scenario. Do not embed scenario policy in UI code. Negative results, infeasible runs, and contradictory findings are valid outputs and must not be removed to strengthen a preferred narrative.

## Evidence and claim standards

Every claim must identify whether its basis is observed, derived, estimated, assumed, optimized, scenario-selected, or a policy judgment. “The model is feasible” means only feasible under its declared inputs. Claims about real capacity, producer acceptance, nutrition adequacy, costs, legal authority, or national readiness require evidence appropriate to that claim.

## Generated files

Do not edit `outputs/reference` or `public/generated` manually. Change source inputs or model code, run `make solve`, inspect the behavioral difference, and commit the regenerated outputs with their manifest. Large artifacts belong in release assets or documented external storage, not Git history.

## Pull requests and review

Keep changes scoped. Complete the pull-request checklist, link an issue or explain the independent rationale, and identify required domain reviewers. Significant changes to nutrition, agronomy, farmer economics, environmental constraints, transportation assumptions, policy interpretation, or national-solution claims require an appropriate domain approval in addition to code review.

Maintainers may request smaller commits, additional evidence, or an architecture decision record. See [GOVERNANCE.md](GOVERNANCE.md), [docs/MAINTAINER_GUIDE.md](docs/MAINTAINER_GUIDE.md), and [SECURITY.md](SECURITY.md).