Contributing¶

git clone https://github.com/Quantile-Labs/touchstone
cd touchstone
uv sync --all-extras --dev
uv run pytest -q

Read CONTRIBUTING.md in the repository first. It is the authority; this page is the orientation.

The shape of it¶

Commit messages are linted. scripts/check_commit_msg.py runs as a hook and in CI, and tests/test_commit_msg.py tests the linter. Install the hooks:

git config core.hooksPath .githooks

main is protected. Changes go in through a pull request.

mypy --strict runs over src/. Not over tests/, deliberately: a wrong fixture fails its own test on the next run, which is a faster and louder signal than a type error.

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest -q

Documentation that describes behaviour has a test¶

This is the rule that matters most here, and it is why the README's console blocks are executed by tests/test_readme_console.py and its pipeline table is checked by tests/test_cli_matches_readme.py.

If you change what a command prints, a test will tell you which document now lies.

Working on this site¶

The site is MkDocs Material, built from docs/ in this repository.

uv sync --group docs
uv run mkdocs serve

Then http://127.0.0.1:8000. It hot-reloads on save, and watch: [src] means a docstring change rebuilds the Reference section too.

uv run mkdocs build --strict

--strict turns broken internal links into build failures. Run it before pushing.

The theme tokens in docs/assets/css/quantile.css are lifted from quantilelabs.com so the two sites are one substrate. If the laboratory site's palette moves, move them here too. The site is light only, because the parent site sets color-scheme: light deliberately and has no dark palette to toggle to.

Where the reference comes from¶

The Contracts page is generated by mkdocstrings from the docstrings in src/touchstone/contracts/. Field docstrings become the field descriptions.

That means a docstring on a pydantic field is published documentation. Write it that way.