Skip to content

Contributing to kloppy

When contributing to this repository, please discuss the change you wish to make with the repository owners via Issues before making the change. This is to ensure that there is nobody already working on the same issue and to ensure your time as a contributor isn't wasted!

How to Contribute

All code changes happen through Pull Requests. If you would like to contribute, follow the steps below to set up the project and make changes:

  1. Fork the repo and create your branch from master.
  2. Make code changes to fix a bug/add features
  3. If you have added new code, add test(s) which cover the changes you have made. If you have updated existing code, verify that the existing tests cover the changes you have made and add/modify tests if needed.
  4. Ensure that tests pass.
  5. Ensure that your code conforms to the coding standard by either using the git hook (see instructions below) or by executing the command black . prior to committing your code.
  6. Commit your code and create your Pull Request. Please specify in your Pull Request what change you have made and please specify if it relates to any existing issues.

Project Setup

After you have forked the code and cloned it to your machine, execute the following commands in order to install all necessary project dependencies. It is recommanded to create a virtual environment.

Environment setup

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# create virtual environment
python3 -m virtualenv .venv
source .venv/bin/activate

# bump dependencies inside virtual env
python -m pip install -U pip setuptools wheel
python -m pip install -e .

# install extra dependencies
python -m pip install -e '.[test]'
python -m pip install -e '.[development]'
python -m pip install -e '.[query]'

Code Formatting

This project uses the black code formatter to ensure all code conforms to a specified format. It is necessary to format the code using black prior to committing. There are two ways to do this, one is to manually run the command black . (to run black on all .py files (or, black <filename.py> to run on a specific file).

Alternatively, it is possible to setup a Git hook to automatically run black upon a git commit command. To do this, follow these instructions:

  • Execute the command pre-commit install to install the Git hook.
  • When you next run a git commit command on the repository, black will run and automatically format any changed files. Note: if black needs to re-format a file, the commit will fail, meaning you will then need to execute git add . and git commit again to commit the files updated by black.

Documentation

This project uses MkDocs to generate documentation from pages written in Markdown.

To build docs :

1
2
3
4
5
# install dependencies for documentation (in virtual env)
python -m pip install -r docs-requirements.txt

# start MkDocs built-in dev-server
mkdocs serve

Open up http://127.0.0.1:8000/ in your browser to preview your documentation.

Contributors (sorted alphabetically)

Many thanks to the following developers for contributing to this project: