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
We maintain a Makefile with several commands to help with common tasks
Install uv
Run uv sync to create a virtual environment and install the dependencies
Install pre-commit using uv: uv tool install pre-commit
Run pre-commit install --install-hooks to install pre-commit hooks

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 but the type hinting itself will be enforced by pyright in the future
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 pyright: ignore once you have verified that the line is correct, but pyright 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. If you are adding a test case, it should be located within the correct submodule of tests. E.g. tests for cadwyn/codegen.py reside in tests/codegen.

make test to run tests located in tests

Running type checkers¶

We use pyright to enforce type safety. You can run it with:

uv run pyright .

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 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