Contributing¶

Contributions to PGTG are welcome. This page describes the development workflow.

Development environment¶

PGTG uses mise to manage the toolchain (Python and uv) and to provide common project tasks. mise pins the versions in .mise.toml, so everyone develops against the same setup.

After installing mise, from the repository root:

mise install     # install the pinned Python + uv toolchain
mise run install # create the .venv and install the ".[all]" extra

mise run install creates a project-local virtual environment in .venv and installs PGTG in editable mode together with all optional dependencies (dev, docs, and examples).

Prefer not to use mise?

Everything mise does is a thin wrapper around uv. You can reproduce it manually with:

uv venv
uv pip install -e ".[all]"

Building and releasing¶

Distribution artifacts are built with poetry-core and can be produced and published with uv (no separate poetry CLI required):

uv build   # build the sdist + wheel into dist/
uv publish # upload dist/ to PyPI (token via UV_PUBLISH_TOKEN)

Common tasks¶

Command	What it does
`mise run install`	Create the venv and install `.[all]`.
`mise run test`	Install the test extra and run `pytest tests/`.
`mise run docs`	Build the documentation into `site/`.
`mise run docs --serve`	Serve the documentation locally with live-reload.

Running the tests¶

mise run test
# or directly:
uv run pytest tests/

The suite covers the environment, map generation, parser, obstacles, traffic rules, and some regression scenarios. Update the tests for any behavior changes or additional features.

Building the documentation¶

The documentation is built with MkDocs and the Material theme, with API pages generated by mkdocstrings from the source docstrings.

mise run docs         # build once (output in site/)
mise run docs --serve # live-preview at http://127.0.0.1:8000

When you add a page, remember to add it to the nav in mkdocs.yml.

Code style and pre-commit¶

The repository uses pre-commit hooks to keep the codebase consistent. mise run install (and mise run test) install the hooks automatically; to do it manually run uv run pre-commit install. The hooks run on every commit, and you can run them across the entire tree at any time:

uv run pre-commit run --all-files

The configured hooks include ruff for formatting (ruff-format; settings in [tool.ruff] / [tool.ruff.format]), pyupgrade, codespell, gitleaks, and a few pre-commit-hooks checks.

Public methods and configuration fields should carry docstrings/annotations, so that they surface directly in the API Reference.