Contributing

Thank you for your interest in contributing to AI4DRPM! This document provides guidelines for contributing to the project.

Development Setup

Prerequisites

  • Python 3.12+

  • PostgreSQL 12+

  • Redis 6.4+

  • Docker and Docker Compose (for containerized development)

  • Poetry (for dependency management)

Local Development Environment

  1. Fork the repository on GitLab

  2. Clone your fork locally:

    git clone https://code.europa.eu/regulatory-reporting/ai4drpm.git

cd ai4drpm

  3. Install dependencies using Poetry:

    poetry install

  4. Set up environment variables:

    cp .env.example .env

# Edit .env with your local configuration

  5. Initialize database:

    # Start PostgreSQL and Redis (via Docker Compose)

docker-compose up -d postgres redis



# Run migrations

poetry run alembic upgrade head

  6. Start the development server:

    poetry run uvicorn ai4drpm.main:app --reload

Code Style

Python

  • Follow PEP 8 style guide

  • Use type hints for all function parameters and return values

  • Write comprehensive docstrings following Google style

  • Keep lines under 100 characters

Type Hints

# Good

def process_document(document: LegalResource, user: User) -> AnalysisResult:

    ...



# Bad (missing type hints)

def process_document(document, user):

    ...

Docstrings

Use Google-style docstrings:

def classify_provision(provision: LegalProvision) -> ClassificationResult:

    """Classify a legal provision using ML model.



    Args:

        provision: The legal provision to classify.



    Returns:

        ClassificationResult with predicted category and confidence score.



    Raises:

        ClassificationError: If classification fails.

    """

    ...

Git Workflow

Branching Strategy

  • main - Production-ready code (protected)

  • development - Integration branch for features

  • feature/* - Individual feature branches

  • fix/* - Bug fix branches

  • refactor/* - Code refactoring branches

Commit Messages

Use Conventional Commits format:

feat: add new pipeline type for provision classification

fix: resolve race condition in bulk operations

fix!: breaking change - update API response format

docs: update architecture documentation

refactor: reorganize repository structure

test: add unit tests for token usage tracking

chore: update dependencies

Pull Request Process

  1. Create an issue first describing the problem or feature

  2. Create a feature branch from development:

    git checkout development

git pull origin development

git checkout -b feature/my-new-feature

  3. Make your changes with atomic, well-described commits

  4. Run tests to ensure nothing is broken:

    pytest tests/ --cov=ai4drpm

  5. Update documentation if the change affects user-facing behavior

  6. Push your branch and create a pull request:

    git push origin feature/my-new-feature

  7. Reference the issue in your PR description

  8. Request review from at least one maintainer

  9. Address feedback and update the PR accordingly

Pull Request Requirements

  • All tests must pass

  • Code coverage must not decrease

  • Documentation must be updated (if applicable)

  • PR title follows conventional commits format

  • PR description clearly explains the changes

Code Review Guidelines

For Contributors

  • Keep PRs focused and small (under 400 lines changed)

  • Include screenshots for UI changes

  • Update CHANGELOG.md for user-facing changes

  • Add tests for new functionality

For Reviewers

  • Focus on code quality, not personal style preferences

  • Request changes for missing tests or documentation

  • Approve when the code meets project standards

  • Be constructive and specific with feedback

Reporting Issues

When reporting issues, please include:

  • Python version

  • Operating system

  • Steps to reproduce

  • Expected vs actual behavior

  • Relevant log output

  • Screenshots (for UI issues)

License

By contributing to this project, you agree to license your contributions under the EUPL-1.2.