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 psycopg2-binary, which includes pre-compiled binaries and requires no system dependencies. If you prefer to build psycopg2 from source, install it explicitly with pip install psycopg2. See the psycopg2 installation guide for system prerequisites.

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
...

Running a full test will also generate a coverage report as part of test output. Writing tests for lines that do not have coverage is a great way to start contributing.

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