Skip to content

Set 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

$ python3 -m venv .venv
$ source .venv/bin/activate
  • Install the development dependencies.
$ poetry install --with dev,test,docs,types --all-extras
  • Install the pre-commit hooks.
$ pre-commit install --install-hooks

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, which is usually sufficient. If you want to run the full test suite, you can sep up dependent services locally with docker:

$ make up
$ 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.