CONTRIBUTING.md

Contributing

Thank you for considering contributing to deepfabric!

When contributing, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

Note that we have a Code of Conduct, please follow it in all your interactions with the project.

Setup

Prerequisites

• Python 3.10 or later

Development

1. Fork and clone the repository

Fork this repository and create your branch from main.

git clone https://github.com/<YOUR-USERNAME>/deepfabric
cd deepfabric

2. Create and activate a virtual environment

We strongly recommend using an isolated virtual environment.

Option A: Using venv (standard Python)

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

Option B: Using uv (recommended)

DeepFabric supports running all development tasks via uv, which provides fast and reproducible environments without manual virtual environment activation.

3. Install the project and development dependencies

DeepFabric uses PEP 621 (pyproject.toml) with Hatch as the build backend.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
pip install -U pip
pip install -e '.[dev]'

Option B: Using `uv` (recommended)

uv sync --extra dev

This installs:

• test dependencies (pytest, pytest-cov, etc.)
• linting and security tools (ruff, bandit)

4. Run the test suite

Ensure all tests pass before submitting changes.

Unit tests (required)

At a minimum, please run the unit test suite. Additional integration and security checks are recommended when relevant.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
pytest tests/unit/

Option B: Using `uv` (recommended)

uv run pytest tests/unit/

Integration tests (optional, but recommended)

Integration tests cover interactions with external systems (e.g. LLM providers). They may require additional environment variables or credentials. Please refer to the Makefile for available integration test targets.

Security checks (optional)

We recommend running security checks before submitting larger or user-facing changes.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
bandit -r deepfabric/

Option B: Using `uv` (recommended)

uv run bandit -r deepfabric/

5. Lint and format the code

Ensure the codebase is properly linted and formatted before submitting changes.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
ruff format deepfabric/ tests/
ruff check . --exclude notebooks/

Option B: Using `uv` (recommended)

uv run ruff format deepfabric/ tests/
uv run ruff check . --exclude notebooks/

6. Commit your changes

We strongly recommend following the Conventional Commits specification when committing:

• feat: new features
• fix: bug fixes
• docs: documentation-only changes
• refactor: code refactoring
• test: adding or updating tests
• chore: tooling and maintenance

Example:

git commit -m "feat: add dataset validation pipeline"

Documentation

1. Install documentation dependencies

DeepFabric uses MkDocs with the Material theme for documentation.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
pip install -U pip
pip install -e '.[docs]'

Option B: Using `uv` (recommended)

uv sync --extra docs

This installs:

• MkDocs and the Material theme (mkdocs-material)
• Python API documentation support via mkdocstrings[python]

2. Writing documentation

• User-facing documentation lives in the docs directory.
• API documentation is generated from Python docstrings via mkdocstrings.
• Please follow the existing style and structure when adding new pages.

3. Docstring conventions

DeepFabric enforces Google-style docstrings, consistent with the ruff configuration:

[tool.ruff.lint.pydocstyle]
convention = "google"

Example:

def load_dataset(path: str) -> Dataset:
    """Load a dataset from disk.

    Args:
        path: Path to the dataset directory.

    Returns:
        The loaded dataset.
    """
    ...

4. Serve the documentation locally

Ensure you can preview the documentation site locally before submitting changes.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
mkdocs serve

Option B: Using `uv` (recommended)

uv run mkdocs serve

5. Build the documentation

Ensure you generate the static documentation site before publishing or submitting changes.

Option A: Standard Python (`venv` + `pip`)

# Make sure your virtual environment is activated.
mkdocs build

Option B: Using `uv` (recommended)

uv run mkdocs build