Contributing Guide

We welcome contributions to pydebeziumai! Below are guidelines to help you set up your local development environment, run formatting/linting tools, build documentation, and execute the test suite.

Please ensure that your contributions follow the general Debezium Contributing Guide (which covers how to structure pull requests, write commit messages, and sign off your commits) as well as the Debezium AI Usage Policy.

Development Environment Setup

Clone the repository and navigate to the project directory:

git clone https://github.com/debezium/debezium-ai-python.git
cd debezium-ai-python

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install the package in editable mode along with development and documentation dependencies:
```
pip install -e ".[dev]"
```

Code Formatting & Linting

We use Ruff for code formatting and linting, and MyPy for typechecking. Before submitting a pull request, run the following checks:

Code Formatting:
```
ruff format .
```
Lint Checks:
```
ruff check --fix .
```
Type Verification:
```
mypy --python-version 3.10 .
```

Running Tests

The test suite contains both unit and integration tests.

Note

Running integration tests requires a Java 17+ runtime and local Debezium JAR files. Ensure JAVA_HOME is configured and the database connector JARs are downloaded before running the tests:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
python3 tools/setup_jars.py
pytest

Building Documentation

To build the HTML documentation locally:

Ensure the documentation requirements are installed (included in the [dev] extra).
Navigate to the docs/ directory and build the HTML output:
```
cd docs
make html
```
The generated HTML pages will be available under docs/_build/html/index.html.