# Contributing

Thank you for improving ModelForge. Small, focused changes with tests and an explicit security
impact are easiest to review.

## Set up

ModelForge requires Python 3.12, Node.js, npm, Docker Engine 24+ and Docker Compose 2+. Each Python
component has its own package metadata; the frontend uses its committed npm lockfile.

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e 'backend[dev]' -e 'node-agent[dev]' -e 'runtime-worker[dev]'
cd frontend && npm ci
```

On Windows, activate with `.venv\Scripts\Activate.ps1`.

## Before opening a change

```bash
python -m ruff check backend/src backend/tests node-agent/src runtime-worker/src
python -m mypy backend/src
python -m mypy --config-file node-agent/pyproject.toml node-agent/src
python -m mypy --config-file runtime-worker/pyproject.toml runtime-worker/src
python -m pytest backend/tests node-agent/tests runtime-worker/tests -q
cd frontend && npm test -- --run && npm run build
```

Also run `git diff --check` and Gitleaks. Do not commit `.env`, credentials, private hostnames,
production evidence, model weights, generated backups or personal data.

## Design rules

- Applications depend on versioned capabilities, never concrete model names.
- Production identities use exact commits, artifact digests and image digests.
- No production promotion occurs without evidence and explicit approval.
- `trust_remote_code` stays false; untrusted model code is not executed.
- Agents and runtime workers use narrow identities and least privilege.
- Destructive actions require a bounded plan, current preconditions and an audit record.
- Do not introduce Kubernetes or inbound compute-node orchestration.

Update user documentation when behavior or configuration changes. Add a migration for schema
changes and prove both the upgrade chain and the PostgreSQL privilege boundary. Security issues must
follow [SECURITY.md](SECURITY.md), not the public issue tracker.