Skip to main content

Getting started

  1. Fork the repository on GitHub
  2. Clone your fork
  3. Install uv — all Python tooling is managed through it

Development setup

The project is a monorepo with multiple Python packages under python_modules/. Each package has its own pyproject.toml managed by uv.

Running tests before submitting

All four test suites must pass:
See Running Tests for details.

Code style

  • Python — code is formatted with ruff. Run uv run ruff format . and uv run ruff check . before committing.
  • Type annotations — all public functions should have type annotations. Run uv run mypy src/ to check.
  • Docstrings — module-level docstrings explain the role of the module. Function docstrings where the behaviour is non-obvious.

Where to make changes

Adding a new config field

  1. Add the field to the appropriate Pydantic model in config/models.py
  2. Update config/normalization.py if the field uses camelCase in YAML
  3. Update Config Reference in the docs
  4. Add a test in tests/test_config.py
  5. If it’s a server field, add the corresponding env var to Environment Variables

Writing integration tests

Use proxy-hopper-testserver to write end-to-end tests against the real server stack:

Pull request process

  1. Create a branch from next
  2. Make your changes with tests
  3. Ensure all test suites pass
  4. Update documentation if you changed behaviour or added a feature
  5. Open a PR against main with a clear description of what and why
  6. Address any review comments

Reporting bugs

Open an issue on GitHub with:
  • Proxy Hopper version (docker inspect ghcr.io/cams-data/proxy-hopper:latest | jq '.[0].Config.Labels')
  • Your config (with credentials redacted)
  • Steps to reproduce
  • Expected vs actual behaviour
  • Relevant log output (use --log-level DEBUG)