CONTRIBUTING.md

Contributing to Toaster

Thanks for helping! This is a small, focused project — the bar is simply: green checks, and the architecture stays clean.

Setup

uv venv && uv pip install -e ".[dev]"     # or: pip install -e ".[dev]"
pre-commit install                         # optional: ruff on every commit

Before you push

make check     # ruff check + ruff format --check + pytest

CI runs exactly this on Python 3.11 and 3.12 for every push and PR. Please keep it green and add a test for any behaviour change (the suite is headless and fast — no GUI needed).

Architecture rules (please keep these)

• toaster.core is numpy-only and headless — it must never import a GUI, a renderer, or a web framework. tests/test_architecture.py enforces this.
• Dependencies flow one way: core ← io / segment / persistence ← interaction ← api / web. The browser receives only numpy arrays and a flat snapshot, never colour buffers.
• The two public extension seams are Segmenter (@register_segmenter) and Loader (register_loader). New built-ins go through them; see the README for worked examples.

Style

• ruff for lint and formatting (config in pyproject.toml).
• Type hints and from __future__ import annotations everywhere; docstrings with Args/Returns on public API.
• Code, comments and docs in English.