Contribution Guide¶

Setting up the environment¶

The easiest way to set up the development environment is to use the provided Makefile. This project requires Astral’s uv for dependency management.

If you do not have uv installed, run: make install-uv
Run the full installation command:
```
make install
```
This command creates a virtual environment, installs the project in editable mode, and sets up all development dependencies.
Install pre-commit hooks:
```
uv run pre-commit install
```

Code contributions¶

Workflow¶

Fork the repository.
Clone your fork locally with git.
Setting up the environment using make install.
Create a branch for your changes.
Make your changes and ensure they follow the project style.
(Optional) Run make lint or uv run pre-commit run --all-files manually to apply fixes and check types before committing.
Commit your changes to git.
Push the changes to your fork.
Open a Pull Request.

Important

Give the pull request a descriptive title indicating what it changes. If it fixes an open issue, include the issue number. For example: fix: update user profile validation logic (#123).

Tip

All commits and pull requests must follow the Conventional Commit format. Before pushing, ensure all tests pass by running make test.

Project documentation¶

The documentation is located in the /docs directory and is built with ReST and Sphinx.

If you are unfamiliar with these tools, read the ReStructuredText primer and the Sphinx quickstart.

Docs theme¶

The project uses the Shibuya theme to maintain a modern and clean look. If you wish to contribute to the docs style or static site generation, please consult the theme documentation.

Running the docs locally¶

To work on the documentation with live-reload (recommended):

make docs-serve

The documentation will be available at http://localhost:8002.

Alternatively, you can build them with:

make docs