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 <https://peps.python.org/pep-0008/>`_ 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

~~~~~~~~~



.. code-block:: python



   # 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 <https://www.conventionalcommits.org/>`_ 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 <https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12>`_.