mantelo/CONTRIBUTING.md

🔧 Contributing

• Prerequisites
• Setting up the environment
• Running checks and tests
• About commits
• How to contribute

Prerequisites

Ensure you have the following available on your machine:

• Python
• Docker

Setting up the environment

To work on this library locally, install the library in edit mode along with the dev dependencies:

# Use .[dev,test] to also install pytest and related libraries
pip install -e '.[dev]'

To spawn the Keycloak Test Server, use the docker-compose.yml (done automatically when running tests, see blow):

docker compose up --wait

The server is configured using the resources in tests/realms and is available at http://localhost:9090. If you need to change anything to the realms, ensure you persist your changes using make export-realms.

Running checks and tests

A Makefile is available for all the usual development tasks. Use help to list the available commands:

make help

Build
  build  Build the wheels and sdist.

Documentation
  docs   Generate the HTML documentation.
  docs-clean  Remove docs build artifacts.
  docs-open  Open the documentation locally (requires make docs to have ran).

Development
  lint   Check formatting and lint with ruff.
  format  Format and auto-fix with ruff.
  test   Run tests with tox (inside docker).
  mypy   Run mypy locally to check types.
  export-realms  Export test realms after changes in Keycloak Test Server.

Note that make test automatically starts a Keycloak container if it isn't already running. You may have to stop it manually. The test server is configured using the resources in tests/realms and is available at http://localhost:9090. To start the Keycloak server yourself:

docker compose up --wait

You can run the tests directly using pytest for faster development, just ensure you installed the test dependencies (pip install -e '.[dev,test]') and Keycloak is running.

About commits

This repository adheres to the Conventional Commits specification and requires signed commits.

How to contribute

1. Fork this repository, develop and test your changes
2. Make sure that your changes do not decrease the test coverage
3. Create signed commits that follow the conventional commits specification
4. If necessary, update the docs
5. Submit a pull request