Contribution Guide¶

Setting up the environment¶

The minimum supported version is Python 3.10. It is recommended to manage multiple Python versions on your system with uv
Running the full local check suite also requires Node.js and npm for link validation
Run make to see the available developer commands
Install uv
Run make install to install the project and standalone developer tools
Run make hooks to install the prek git hooks
Run make check to verify that the local CI-equivalent checks pass

make install uses uv to create the project environment with every development and optional dependency. It also installs prek and tox with the tox-uv plugin as standalone tools so repeated checks start quickly.

Skip make hooks if you already manage hooks with Git's core.hooksPath setting. You can still run every hook manually with make lint.

Code contributions¶

Workflow¶

Fork the Cadwyn repository
Clone your fork locally with git
Set up the environment
Make your changes
Commit your changes to git
Push the changes
Open a pull request. Give the pull request a descriptive title indicating what was changed

Guidelines for writing code¶

Code should be Pythonic and zen
All code should be fully typed. This is enforced via ruff and ty
When complex types are required, use type aliases
If something cannot be typed correctly due to the limitations of the type checkers, use typing.cast to resolve the issue. However, use typing.cast only as a last resort, after exhausting all other options of type narrowing, such as isinstance() checks and type guards
Use ty: ignore once you have verified that the line is correct, but ty has issues with it
If you are adding or modifying existing code, make sure that it's fully tested. 100% test coverage is mandatory, and will be checked on the PR using Github Actions
When adding a new public interface, make sure you have included it in the concept documentation located in docs/concepts.md. If applicable, add or modify examples in the docs related to the new functionality

Writing and running tests¶

Tests are contained within the tests directory, and follow roughly the same directory structure as the cadwyn module. Place each test according to the public interface it exercises. If a test has no natural location in that structure, check whether it is testing an internal implementation detail that would be better covered through a public interface.

Keep tests atomic. Separate distinct positive and negative scenarios, and use parametrization when the same behavior needs to be checked with several inputs.

make check runs the local CI-equivalent suite with tox's default automatic parallelism. It runs the supported Python test matrix, tutorial tests, coverage, prek linting, documentation build, link validation, and package build checks. Each supported Python test environment runs ty before its tests.

If prek, tox, or the tox-uv plugin is missing, the Makefile will stop early and print the matching uv tool install ... command to install it.

Use make lint to run only the prek hooks. For a focused test run, use uv run pytest followed by the test path and any pytest options.

Name tests using the what, when, expected convention:

test__{what}__{when}__{expected}

what is the function or public interface under test, when describes the conditions in which it is exercised, and expected states the observable result. Prefer concrete outcomes such as should_return_404 or should_raise_router_generation_error over generic suffixes such as error, ok, or numbered variants. A test name should let a reader understand a failure without first opening its implementation.

Running type checkers¶

We use ty to enforce type safety. It runs before the test suite on every supported Python version. You can run it against your active project environment with:

uv run ty check

Project documentation¶

The documentation is located in the /docs directory and uses Markdown.

Docs theme and appearance¶

We welcome contributions that improve the appearance and usability of the docs. We use mkdocs-material If you wish to contribute to the docs style / setup, or static site generation, consult the theme docs as a first step.

Running the docs locally¶

After improving the docs, serve the documentation with uv run mkdocs serve.

Writing and editing docs¶

We welcome contributions that improve the content of the docs. Feel free to add examples, clarify text, restructure the docs, etc., but make sure to follow these guidelines:

Write text in idiomatic, simple English
Opt for Oxford commas when listing a series of terms
Keep examples simple and self contained
Provide links where applicable