CONTRIBUTING.md

Contributing

Prerequisites

• Python 3.10+
• Modal CLI (pip install modal)
• A GitHub Personal Access Token with Actions permissions (for integration testing)

Setup

pip install -e ".[dev]"

This installs runtime dependencies (modal, httpx, fastapi) and dev tools (pytest, pytest-asyncio, ruff).

Development

Run the local dev server:

make serve

Deploy to Modal:

make deploy

Testing

make test

Tests use pytest with pytest-asyncio. The test suite mocks Modal and external HTTP calls, so no Modal credentials are needed to run tests locally.

Adding new tests

Tests live in tests/test_app.py. Follow existing patterns:

• Use _make_request() and _make_webhook_body() helpers for webhook tests
• Use _next_delivery_id() for unique delivery IDs (prevents dedup cache collisions)
• Mock app.modal via patch("app.modal") for GPU tests
• Mock app._call_github_api for GitHub API tests
• Mark async tests with @pytest.mark.asyncio

Linting

make lint

Uses ruff with rules: E, F, W, I. Line length: 120. Target: Python 3.10.

Commit conventions

Use Conventional Commits:

• feat: new features
• fix: bug fixes
• docs: documentation changes
• test: test additions or changes
• refactor: code restructuring
• chore: build, CI, or tooling changes

Pull requests

• Keep PRs focused on a single change
• Ensure make test and make lint pass before pushing
• Add tests for any new functionality