Developer Onboarding

Use a repository-local virtual environment for Modelwright development. This keeps package dependencies, console scripts, Sphinx, and quality tools tied to the checkout being edited.

Bootstrap

From the repository root:

scripts/bootstrap_dev_env.sh

This creates .venv/ and installs Modelwright with the dev extra:

.venv/bin/python -m pip install -e '.[dev]'

The editable install handles code and development dependencies only. It does not download external workbook assets as an install side effect.

To also restore the public FABLE benchmark workbooks into canonical ignored paths, run:

scripts/bootstrap_dev_env.sh --benchmarks

Activate manually when needed:

source .venv/bin/activate

Best Practices

  • Use .venv/bin/python and .venv/bin/sphinx-build in local commands.

  • Keep .venv/ untracked.

  • Run checks before committing:

    .venv/bin/python -m ruff check .
.venv/bin/python -m pytest
.venv/bin/sphinx-build -b html docs _build/html -W

  • Store private workbooks and generated outputs under ignored tmp/ paths.

  • Do not commit raw workbook files, generated clones, private logs, or full private validation reports.

  • Update ROADMAP.md and CHANGE_LOG.md with each completed task.

Where To Look

  • README.md: quick project overview and common commands.

  • CONTRIBUTING.md: contributor workflow and data hygiene.

  • AGENTS.md: working contract for AI-assisted development.

  • ROADMAP.md: active phase and next task.

  • planning/: detailed design notes and implementation decisions.