Skip to content

Setting up Protean locally

Thank you for considering contributing to Protean!

First time local setup

  • Download and install git.
  • Configure git with your username_ and email.
$ git config --global user.name 'your name'
$ git config --global user.email 'your email'
  • Make sure you have a GitHub account.
  • Fork Protean to your GitHub account by clicking the fork button.
  • Clone the main repository locally.
$ git clone https://github.com/proteanhq/protean
$ cd protean
  • Add your fork as a remote to push your work to. Replace username with your GitHub username. This names the remote "fork", the default Protean remote is "origin".
$ git remote add fork https://github.com/{username}/protean
  • Install uv.
$ curl -LsSf https://astral.sh/uv/install.sh | sh
  • Install development dependencies. uv will automatically create a virtual environment in .venv.
$ uv sync --all-extras --all-groups
  • Install pre-commit hooks.
$ pre-commit install --install-hooks
  • The postgresql extra installs psycopg 3 with its pre-compiled binary package, and the postgresql-psycopg2 extra installs psycopg2-binary. --all-extras installs both, so the test suite can run on either driver. Neither needs system dependencies.

Start coding

  • Create a branch to identify the issue you would like to work on. If you're submitting a bug or documentation fix, branch off of the latest ".x" branch.
$ git fetch origin
$ git checkout -b your-branch-name origin/0.11.x

If you're submitting a feature addition or change, branch off of the "main" branch.

$ git fetch origin
$ git checkout -b your-branch-name origin/main
  • Using your favorite editor, make your changes, committing as you go.
  • Include tests that cover any code changes you make. Make sure the test fails without your patch. Run the tests as described below.
  • Push your commits to your fork on GitHub and create a pull request.
  • Link to the issue being addressed with fixes #123 or closes #123 in the pull request.
$ git push --set-upstream fork your-branch-name

Running Tests

Run the basic test suite with:

$ protean test

This runs the basic tests for the current environment. To run the full test suite, you can set up dependent services locally with docker:

$ make up
...
docker-compose up -d redis elasticsearch postgres message-db
[+] Running 4/4
 ✔ Container protean-postgres-1       Running
 ✔ Container protean-elasticsearch-1  Running
 ✔ Container protean-message-db-1     Running
 ✔ Container protean-redis-1          Running
...
$ protean test -c FULL
...

Any OCI container engine works, not just Docker

These services run on any OCI-compatible container engine. Protean's test harness connects to the service ports on localhost, so it is agnostic to what starts the containers. OrbStack, Podman, Colima, and Rancher Desktop all work with the same docker-compose.yml. For Podman, run podman compose directly or point docker-compose (or docker compose) at the Podman socket via DOCKER_HOST.

Running a full test will also generate a coverage report as part of test output. An uncovered line is a good place to start contributing: find the behaviour that runs it and test that behaviour (see Do not write a test only to reach a line).

For more detailed information about testing, please refer to the Testing Guide.