Contributing

Thank you for your interest in contributing to Divi! This guide will help you get started with our development workflow.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/divi.git
cd divi

Install development dependencies:
```
poetry install --with dev,testing,docs
```
Set up pre-commit hooks (recommended):
```
poetry run pre-commit install
```

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Development Environment

Divi uses Poetry for dependency management with several groups:

dev: Core development tools (Black, isort, pre-commit)
testing: Testing framework and utilities (pytest, pytest-mock, flaky)
docs: Documentation building (Sphinx, nbsphinx)
ui: Dashboard and visualization tools (Dash, Bootstrap)
jupyter: Jupyter notebook support (ipywidgets)

Install specific groups as needed:

poetry install --with dev,testing  # For core development
poetry install --with docs         # For documentation work
poetry install --with ui           # For dashboard development

Code Quality & Style

We maintain high code quality through automated tools:

Pre-commit Hooks (Recommended)

Pre-commit hooks automatically run quality checks before each commit:

Black: Code formatting (Black)
isort: Import sorting (isort with Black-compatible profile)
License Headers: Automatic SPDX license header insertion
File Validation: JSON, YAML, TOML syntax checking
Line Endings: CRLF/tab enforcement

Manual Quality Checks

If you prefer manual control:

poetry run black .
poetry run isort .
poetry run pytest

License Compliance

All Python files must include SPDX license headers. The pre-commit hook automatically adds them, but you can also add manually:

# SPDX-FileCopyrightText: 2025 Qoro Quantum Ltd <divi@qoroquantum.de>
#
# SPDX-License-Identifier: Apache-2.0

Pull Request Process

Write tests for your changes (see Testing)
Update documentation if needed (see Building Documentation)
Ensure pre-commit hooks pass (or run quality checks manually)
Run the test suite: poetry run pytest
Submit a pull request with a clear description

Pro Tips: - Use descriptive commit messages - Reference related issues in your PR description - Keep PRs focused on a single feature/fix - Ensure all CI checks pass

For more details, see our Contributing Guidelines.