# Contributing to oehrpy

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

## Table of Contents

- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Development Workflow](#development-workflow)
- [Code Standards](#code-standards)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Types of Contributions](#types-of-contributions)

## Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/oehrpy.git
   cd oehrpy
   ```
3. Add the upstream repository as a remote:
   ```bash
   git remote add upstream https://github.com/platzhersh/oehrpy.git
   ```

## Development Setup

### Prerequisites

- Python 3.10 or higher
- pip

### Installation

Install the package in editable mode with development dependencies:

```bash
pip install -e ".[dev,generator]"
```

This installs:
- **Runtime dependencies**: pydantic, httpx, defusedxml
- **Dev dependencies**: pytest, pytest-asyncio, mypy, ruff
- **Generator dependencies**: jinja2, lxml (for code generation)

## Development Workflow

### Running Checks

Before submitting a pull request, ensure all checks pass:

```bash
# Run linter
ruff check .

# Check formatting
ruff format --check .

# Run type checking
mypy src/openehr_sdk

# Run unit tests
pytest tests/ -v
```

### Auto-formatting Code

To automatically format your code:

```bash
ruff format .
```

### Running Tests with Coverage

```bash
pytest tests/ -v --tb=short --cov=src/openehr_sdk --cov-report=term-missing
```

## Code Standards

### Python Version

The project targets Python 3.10+ and uses modern type hints (e.g., `X | None`, `list[str]`).

### Naming Conventions

- **RM classes**: Use UPPERCASE names to match openEHR specifications (e.g., `DV_QUANTITY`, `CODE_PHRASE`)
- **General code**: Follow PEP 8 naming conventions
- **ElementTree**: The abbreviation `ET` is allowed for ElementTree imports

### Generated Code

The RM classes in `src/openehr_sdk/rm/rm_types.py` are generated from openEHR specifications. Do not edit this file manually. To regenerate:

```bash
python -m generator.pydantic_generator
```

### Linting Configuration

The project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Configuration is in `pyproject.toml`. Some files have special ignore rules for generated code and long test assertions.

### Type Checking

The project uses mypy in strict mode. All new code should be fully typed.

## Testing

### Unit Tests

Unit tests are located in `tests/` and cover:
- RM class instantiation and validation
- Serialization (canonical JSON and FLAT format)
- OPT parsing and builder generation
- AQL query building

Run unit tests:
```bash
pytest tests/ -m "not integration" -v
```

### Integration Tests

Integration tests validate the SDK against a real EHRBase instance. They require Docker.

#### Running Integration Tests Locally

```bash
# Start EHRBase with Docker Compose
docker-compose up -d

# Wait for services to be healthy (60-90 seconds)
docker-compose ps

# Run integration tests
pytest tests/ -m integration -v

# Clean up
docker-compose down -v
```

#### Writing Integration Tests

- Use the `@pytest.mark.integration` marker
- Place tests in `tests/integration/`
- Use fixtures from `tests/integration/conftest.py` for EHRBase client and test data

## Submitting Changes

### Creating a Branch

Create a feature branch from `main`:

```bash
git checkout main
git pull upstream main
git checkout -b feature/your-feature-name
```

### Commit Messages

Write clear, descriptive commit messages:
- Use the imperative mood ("Add feature" not "Added feature")
- Keep the first line under 72 characters
- Reference issues where applicable (e.g., "Fix #123")

### Pull Request Process

1. Ensure all checks pass (lint, type-check, tests)
2. Update documentation if needed
3. Push your branch to your fork
4. Create a pull request against `main`
5. Fill out the PR template with:
   - A clear description of changes
   - Related issue numbers
   - Testing performed

### Code Review

- All PRs require review before merging
- Address review feedback promptly
- Keep PRs focused and reasonably sized

## Types of Contributions

### Bug Reports

When reporting bugs, please include:
- Python version
- oehrpy version
- EHRBase version (if applicable)
- Steps to reproduce
- Expected vs actual behavior
- Error messages or stack traces

### Feature Requests

For feature requests, please describe:
- The use case
- Proposed solution
- Alternatives considered

### Documentation

Documentation improvements are always welcome:
- Fix typos or unclear explanations
- Add examples
- Improve API documentation

### Code Contributions

Areas where contributions are particularly welcome:
- Additional template builders for common clinical templates
- Improved error messages and validation
- Performance optimizations
- Additional serialization formats

## Questions?

If you have questions about contributing, feel free to:
- Open a GitHub issue
- Start a discussion in the repository

Thank you for contributing to oehrpy!
