# Contributing to Piggie

Thanks for your interest in contributing to Piggie! This guide covers how to set up a development environment, run tests, and submit changes.

## Development Setup

Piggie requires Python 3.10+ and uses [uv](https://github.com/astral-sh/uv) for package management.

```bash
# Clone the repo
git clone https://github.com/gregfelice/piggie.git
cd piggie

# Create virtualenv and install in dev mode
uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

### Database Requirements

Integration tests require PostgreSQL with Apache AGE and pgvector extensions. See the [documentation](https://piggie.ooxo.io/guide/quickstart/) for setup instructions.

Unit tests run without a database:

```bash
pytest tests/test_types.py tests/test_result.py tests/test_cypher_wrapper.py tests/test_agtype_parser.py
```

## Running Tests

```bash
# All tests (requires PostgreSQL with AGE + pgvector)
pytest tests/ -v

# Unit tests only (no database needed)
pytest tests/test_types.py tests/test_result.py tests/test_cypher_wrapper.py tests/test_agtype_parser.py

# Integration tests only
pytest tests/ -m integration
```

## Code Style

We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy-lang.org/) for type checking.

```bash
# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/piggie --exclude 'src/piggie/_agtype/gen'
```

Run these before submitting a PR. All checks must pass.

## Conventions

- Type hints on all public APIs
- Docstrings on public classes and methods
- Tests for new functionality
- Keep the agtype parser generated code (`src/piggie/_agtype/gen/`) untouched — it's auto-generated from the ANTLR grammar

## Submitting Changes

1. Fork the repo and create a feature branch
2. Make your changes
3. Run `ruff check`, `ruff format`, and `mypy` — all must pass
4. Run the relevant tests
5. Open a pull request with a clear description of what changed and why

## License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 license.
