Contributing to repid

Your contributions are invaluable to our community - thank you for being a part of the journey!

Development setup

Quick overview

1. Create a fork of repid
2. Clone your fork
3. Install PDM
4. Install dependencies in virtual environment
5. Configure pre-commit
6. Make your changes!

Detailed guide

Create a fork and clone the repo

First of all, you will need to create a fork.

Clone it and cd into the directory:

git clone https://github.com/__your_username__/repid.git
cd repid

PDM & venv

Repid uses PDM to manage virtual environment, dependencies & package the project.

Tip

Use brew or pipx when installing PDM to keep your system Python clean.

brew install pdm

pipx install pdm

After installation is done, run the following command in the project's root directory:

pdm install --group :all

It will create virtual environment and install inside of it all dependencies, including those, which are needed for development.

Important

Use lowest supported by repid version of Python (== 3.8 for now) for your venv.

You can use pyenv to set up multiple versions of Python on your system.

To activate a venv run:

$(pdm venv activate)

...or simply execute the needed command with pdm run prefix, e.g.

pdm run mkdocs serve

pre-commit

repid uses pre-commit to run linters and formatters. To initialize pre-commit run:

pdm run pre-commit install --install-hooks

If you want to run all linters and formatters, execute the following command:

pdm run pre-commit run -a

If you want to commit some changes disregarding pre-commit hooks, add -n or --no-verify flag to git commit command.

Important

Keep in mind that when you will submit your pull request, all the hooks must pass in CI anyway, or, unfortunately, we will have to decline your contribution.

Make your changes

Make your changes, create commits and submit a pull request.

Here are some advices:

1. Commits:

   • Please use gitmoji to prefix your commit messages
   • Try to make commits atomic
   • gitmoji should describe type of the change, while commit message shows the exact change in behavior, e.g.

   ♻️ Refactored _signal_emitter property and wrapping in new into a separate _WrapperABC class
   

2. Issues:

   • Please use one of provided templates to create an issue
   • Make it as much descriptive as possible

3. Pull requests:

   • If your pull request isn't very simple (like fixing a typo in the docs) - please create an issue first, so we can discuss it
   • Mark pull request as a resolver for the related issue(-s)
   • Please complete the checklist provided in the pull request template
   • Please avoid creating very large pull requests

Running tests locally

You will need docker to run tests locally.

Apart from that, everything is automated via pytest (including creation of containers for integration testing!), so all you need to do is:

pdm run pytest

If you want to run test suite with all default arguments already set up - there is a PDM script:

pdm run test

VSCode and Dev Container

If you are willing to use VSCode, repid comes with some configs already in place. Feel free to modify them up to your liking, but be careful not to commit any changes unintentionally.

Another quality-of-life feature is Dev Container. Essentially it is a bunch of configs, which describe how to create a docker container, that comes with VSCode server, all the necessary plugins and a virtual environment already set up. You can use it with GitHub Codespaces to create it in one click and start developing right away!