# Developer guide

The project follows the standard ESRF Ewoks applications designes.

## Local environment

Create a virtual environment and install the development extras:

``` bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"
```

This brings the `test` extra together with the linters and formatters
used by the CI.

## Run the test suite

``` bash
pytest
```

Unit tests live under `src/ewokstomo/tests`. Some tests rely on
ESRF datasets stored in `src/ewokstomo/tests/data`; keep fixtures
small so that they remain version-control friendly.

## Linting and formatting

- `ruff check .` – static analysis and style hints.
- `ruff format .` – code formatting.
- `bandit -r .` – basic security checks.

CI pipelines mirror these tools; run them locally before submitting a
merge request to reduce turnaround time.

## Documentation

The Sphinx documentation lives under `doc`. Regenerate the HTML locally
with:

``` bash
pip install -e ".[doc]"
sphinx-build -b html doc doc/_build/html
```

The index page follows the structure used by the Ewoks application
family. When you introduce a new task follow the input and output 
Pydantic models.

## Coding conventions

- Prefer explicit typing; type hints are surfaced in the generated API
  docs.
- Keep task inputs/outputs stable for downstream workflows. When a
  breaking change is required, update all bundled workflow JSON files
  and record the change in the changelog (for ESRF tasks, apply the
  changes to Blissoda).
- Tests should focus on behaviour (expected outputs, error handling)
  rather than internal implementation details. Try to test the task, 
  its methods and a complete workflow to increate robustness.