Contribution Guide¶

Setting Up the Environment¶

1. Run make install-uv to install uv if not already installed.
2. Run make install to install all dependencies and pre-commit hooks.

Code Contributions¶

Workflow¶

1. Fork the litestar-granian repository.
2. Clone your fork locally with git.
3. Set up the environment.
4. Make your changes.
5. Run make lint or uvx prek run --all-files to run linters and formatters.
6. Commit your changes to git.
7. Push the changes to your fork.
8. Open a pull request with a descriptive Conventional Commit title indicating what it changes.

Guidelines for Writing Code¶

• All code must be strictly typed and validated with mypy and Pyright.
• All code must be tested with pytest.
• All code must be formatted and linted with Ruff.

Writing and Running Tests¶

Run the complete test suite with make test. Use a focused uv run pytest path/to/test_file.py command while developing, then run make lint, make type-check, make docs, and make build before release.

Runtime changes should cover both focused command-building behavior and real subprocess shutdown. Signal tests must target the top-level Litestar PID and verify that the port closes, server lifespans unwind, and no Granian descendant is orphaned.

Project Documentation¶

The documentation lives in the docs/ directory and is built with Zensical and mkdocstrings-python.

Running the Docs Locally¶

Serve the documentation locally with make docs-serve or build and verify all documentation artifacts with make docs.

Creating a New Release¶

1. Increment the version in pyproject.toml following Semantic Versioning and PEP 440.
2. Draft a new release on GitHub using vMAJOR.MINOR.PATCH as both the tag and release title.
3. Commit your changes and push to main.
4. Publish the release and verify that the GitHub Actions release workflow completes cleanly.