CONTRIBUTING.md

# Contributing to Paper Trail API

Thank you for your interest in contributing to Paper Trail API! This document provides guidelines and instructions for contributing.

## Development Setup

### Prerequisites

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) (recommended package manager)
- Git

### Getting Started

1. **Clone the repository**
   ```bash
   git clone https://github.com/Operation-Hope/paper-trail-api.git
   cd paper-trail-api
   ```

2. **Create a virtual environment and install dependencies**
   ```bash
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync --all-extras
   ```

3. **Install the duckdb-loader package in development mode**
   ```bash
   uv pip install -e duckdb_loader/
   ```

4. **Set up pre-commit hooks**
   ```bash
   uv run pre-commit install
   ```

5. **Copy environment template**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

## Development Workflow

### Code Quality

We use the following tools to maintain code quality:

- **[Ruff](https://docs.astral.sh/ruff/)** - Linting and formatting
- **[ty](https://github.com/astral-sh/ty)** - Type checking
- **[pytest](https://pytest.org/)** - Testing

### Running Checks Locally

```bash
# Linting
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Formatting
uv run ruff format .

# Type checking
uv run ty check duckdb_loader/

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ --cov=duckdb_loader --cov-report=term-missing
```

### Pre-commit Hooks

Pre-commit hooks run automatically on `git commit`. They check:
- Ruff linting and formatting
- Trailing whitespace
- YAML validity
- Large files
- Merge conflicts
- Private keys

To run hooks manually:
```bash
uv run pre-commit run --all-files
```

## Making Changes

### Branch Naming

Use descriptive branch names:
- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation updates
- `refactor/description` - Code refactoring

### Commit Messages

Write clear, concise commit messages:
- Use present tense ("Add feature" not "Added feature")
- First line should be 50 characters or less
- Include context in the body if needed

Example:
```
Add cycle filter preset for recent elections

Adds `recent_cycles(n)` function that returns a CycleFilter
for the last N election cycles, defaulting to 4 (2018-2024).
```

### Pull Requests

1. Create a feature branch from `main`
2. Make your changes
3. Ensure all checks pass locally
4. Push your branch and create a PR
5. Fill out the PR template
6. Request review

PR titles should be descriptive and follow the same guidelines as commit messages.

## Testing

### Running Tests

```bash
# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_filters.py -v

# Run specific test class or function
uv run pytest tests/test_filters.py::TestCycleFilter -v
uv run pytest tests/test_filters.py::TestCycleFilter::test_single_cycle_match -v

# Run with coverage
uv run pytest tests/ --cov=duckdb_loader --cov-report=html
```

### Writing Tests

- Place tests in the `tests/` directory
- Name test files `test_*.py`
- Name test functions `test_*`
- Use fixtures from `conftest.py` for shared data
- Add markers for slow or integration tests:
  ```python
  @pytest.mark.slow
  def test_large_dataset():
      ...

  @pytest.mark.integration
  def test_postgres_connection():
      ...
  ```

### Test Coverage

We aim for high test coverage on core functionality:
- Filters and filter presets
- Schema creation and validation
- Data loading logic (unit tests with mocks)

## Project Structure

```
paper-trail-api/
├── duckdb_loader/           # Main Python package
│   └── duckdb_loader/       # Package source
│       ├── cli.py           # CLI commands
│       ├── filters.py       # Data filters
│       ├── loader.py        # DuckDB loading
│       ├── postgres_loader.py # PostgreSQL loading
│       └── schema.py        # Schema definitions
├── scripts/                 # Utility scripts
├── tests/                   # Test suite
├── docs/                    # Documentation
├── database/                # SQL schemas
├── examples/                # Usage examples
└── data/                    # Data storage (gitignored)
```

## Code Style

### Python

- Follow PEP 8 (enforced by Ruff)
- Use type hints for function signatures
- Write docstrings for public functions and classes
- Keep functions focused and small
- Prefer composition over inheritance

### Documentation

- Update README.md for user-facing changes
- Add docstrings for new public APIs
- Update examples if behavior changes

## Getting Help

- Open an issue for bugs or feature requests
- Check existing issues before creating new ones
- Join discussions in pull requests

## License

By contributing, you agree that your contributions will be licensed under the MIT License.