Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
117 lines (89 loc) · 4.5 KB

CONTRIBUTING.md

File metadata and controls

117 lines (89 loc) · 4.5 KB

Contributing to Patter

Thank you for your interest in contributing to Patter!

Development Setup

Python SDK

cd libraries/python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

Note: the legacy [local] extra is now an empty alias kept only for backwards compatibility — [dev] is sufficient.

TypeScript SDK

cd libraries/typescript
npm install
npm test
npm run build

Pull Request Process

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Write tests first (TDD)
  4. Implement the feature
  5. Ensure all tests pass: pytest tests/ -v / npm test
  6. Commit with conventional commits: feat:, fix:, docs:
  7. Validate locally: bash scripts/pr-validate.sh (see below)
  8. Open a Pull Request against main

Before you open a PR — checklist

These are the things CI (and reviewers) will block on. Catch them locally:

  • Both SDKs. Every user-visible feature ships in Python AND TypeScript in the same PR — same API shape and defaults, snake_case ↔ camelCase. There is no "Python-only" / "TS-only" public surface.
  • CHANGELOG.md. Add an entry under ## Unreleased (### Added / ### Changed / ### Fixed / …) for any user-visible change. Pure refactors, test-only, and docs-only diffs are exempt.
  • bash scripts/pr-validate.sh is green (mirrors the PR-blocking CI).
  • No external license headers / "ported from " provenance comments in source. Naming a provider/carrier you integrate (Twilio, Telnyx, Plivo, OpenAI, …) is fine; copying a competitor's lineage is not.

AI agents (Claude Code, Cursor, Codex, …): see AGENTS.md for the same checklist in a machine-readable form.

Pre-PR validation

Run every PR-blocking CI check locally before opening the PR:

bash scripts/pr-validate.sh           # default: ~3-5 min
bash scripts/pr-validate.sh --quick   # pre-commit + lint (~30s)
bash scripts/pr-validate.sh --full    # default + e2e + all-extras (~10 min)

The script mirrors .github/workflows/test.yml so a green local run lines up with green CI. Selective skips: --skip-py, --skip-ts, --no-stop.

First-time setup:

pip install pre-commit==3.8.0          # required
brew install gitleaks                   # optional — system fallback

If pre-commit's bundled tools don't work on your machine (hardened macOS, Go OOM during gitleaks build), use the documented escape hatches:

PR_VALIDATE_SKIP_GITLEAKS=1 PR_VALIDATE_SKIP_NBSTRIPOUT=1 bash scripts/pr-validate.sh

CI always runs the full unaltered suite, so these only affect local runs.

Code Style

Python

  • Follow PEP 8
  • Use type hints on all public methods
  • Use logging.getLogger("getpatter") — never print()
  • Frozen dataclasses for models
  • Async everywhere — no blocking I/O

TypeScript

  • Strict TypeScript — no any
  • Use WebSocket.OPEN not magic numbers
  • Export all public types from index.ts
  • xmlEscape() for all TwiML strings

Adding a New Provider

Patter uses an instance-based class pattern (post-0.5.0). To add a new STT, TTS, or LLM provider:

  1. Create the provider class:
    • Python: libraries/python/getpatter/stt/<name>.py, libraries/python/getpatter/tts/<name>.py, or libraries/python/getpatter/llm/<name>.py exporting a class named STT, TTS, or LLM.
    • TypeScript: libraries/typescript/src/stt/<name>.ts, libraries/typescript/src/tts/<name>.ts, or libraries/typescript/src/llm/<name>.ts exporting STT, TTS, or LLM.
  2. Read credentials from the standard env var (e.g. <NAME>_API_KEY) when no api_key / apiKey is passed; throw a clear error when both are missing.
  3. Re-export a flat alias from the package barrel (getpatter/__init__.py for Python, libraries/typescript/src/index.ts for TypeScript) — for example STT as DeepgramSTT.
  4. Wire the new class into the pipeline dispatch (stream handler) for end-to-end audio flow.
  5. Add a default pricing entry under DEFAULT_PRICING so users see real cost numbers in the dashboard.
  6. Add unit + integration tests; aim for 80%+ coverage on the new module.
  7. Update the docs: docs/{python,typescript}-sdk/{stt,tts,llm}.mdx and the per-provider page under docs/{python,typescript}-sdk/providers/<name>.mdx if applicable.

Reporting Issues

  • Use the issue templates
  • Include SDK version, Node/Python version, OS
  • Enable debug logging: logging.getLogger("getpatter").setLevel(logging.DEBUG)