Contributing¶

Python 3.11–3.14 are supported, and CI runs the full matrix.

Setup¶

The project uses mise and Poetry.

$ mise install
$ poetry install

Checks¶

Tasks are defined in mise.toml; mise tasks lists them all.

$ mise run test:py      # the test suite
$ mise run lint:py      # ruff, mypy, pylint, import-linter, codespell, vulture
$ mise run format       # black, ruff --fix, taplo

tingle dogfoods its own CI gate — tingle check runs on every pull request, so a branch that takes on debt fails the build.

Docs¶

The documentation site is MkDocs + Material, built from docs/ and published to GitHub Pages from main.

$ mise run docs:serve   # live-reloading preview on localhost:8000
$ mise run docs:build   # strict build; fails on broken internal links

The docs dependency group is optional, so a plain poetry install does not pull in MkDocs. Both tasks install it on demand.

Architecture¶

The source follows the GLIMPSE layout, and the layer boundaries are enforced by import-linter contracts in pyproject.toml — a violating import fails CI.

Layer	Responsibility
`pacts`	contracts — depends on nothing
`specs`	invariants — depends only on `pacts`
`mills`	logic, no IO
`links`	IO adapters
`gates`	CLI
`inits`	wiring

specs is imported only by mills; gates and inits reach it indirectly through mills, which is by design.