Contribution Guide¶

Setting up the environment¶

The lowest currently supported version is Python 3.10. You can use pyenv to manage multiple Python versions on your system.
We maintain a Makefile with several commands to help with common tasks.
Install Poetry
Run poetry install --all-extras to create a virtual environment and install the required development dependencies
Install pre-commit
Run pre-commit install --install-hooks to install pre-commit hooks

Many modern IDEs like PyCharm or VS Code will enable the Poetry-managed virtualenv that is created in step 2 for you automatically. If your IDE/editor does not offer this functionality, then you will need to manually activate the virtualenv yourself. Otherwise you may encounter errors or unexpected behaviour when trying to run the commands referenced within this document.

To activate the virtualenv, please consult Poetry's documentation on working with virtual environments.

The rest of this document will assume this environment is active wherever commands are referenced.

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.
Open a pull request. Give the pull request a descriptive title indicating what it changes.

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 requiring complex types, use a type alias.
If something cannot be typed correctly due to a limitation of the type checkers, you may use typing.cast to rectify the situation. However, you should only use as a last resort if you've exhausted all other options of type narrowing, such as isinstance() checks and type guards
You may use pyright: ignore if you ensured that a line is correct, but pyright has issues with it.
If you are adding or modifying existing code, ensure 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, it has to be included in the concept documentation located in docs/concepts.md. If applicable, add or modify examples in the docs related to the new functionality implemented.

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.

The Makefile includes several commands for running tests:

make test to run tests located in tests
make supertest will run tests on both pydantic 1 and pydantic 2

Running type checkers¶

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

pyright .

Project documentation¶

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

Docs theme and appearance¶

We welcome contributions that enhance / 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, you should consult the theme docs as a first step.

Running the docs locally¶

Then you can serve the documentation with mkdocs serve

Writing and editing docs¶

We welcome contributions that enhance / 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 english, using simple language
Opt for Oxford commas when listing a series of terms
Keep examples simple and self contained
Provide links where applicable