Contributor Guide#

Step-by-step#

This guide will take you through the necessary steps in order to contribute code to the repository.

1. Setup#

If you are not super familiar with the terminology of forking, pull request etc, here is a git tutorial to get you started.

Fork the main repository, and clone your fork onto the machine of your choice.

Make sure to install and activate the environment with:

conda create -n gcm-filters-env -c conda-forge --file requirements.txt --file requirements-dev.txt

If you find that conda takes a long time, try to install mamba with conda install mamba and then and do:

mamba create -n gcm-filters-env -c conda-forge --file requirements.txt --file requirements-dev.txt

and finally activate the environment:

conda activate gcm-filters-env

Before you can efficiently test your code you need to install this package in the now activated environment:

pip install -e . --no-deps

For the linting also install pre-commit now:

pre-commit install

2. Write your code#

This one is pretty obvious 😁

3. Write and run tests#

Now figure out a good way to test the functionality of your code and run the test suite with:

pytest

You will likely have to iterate here several times until all tests pass.

4. Linting and Docstrings#

Once your tests pass, you want to make sure that all the code is formatted properly and has docstrings.

Run all the linters with:

pre-commit run --all-files

Some things will automatically be reformatted, others need manual fixes. Follow the instructions in the terminal until all checks pass.

Once you got everything to pass, you can stage and commit your changes and push them to the remote github repository.

How to change the documentation#

In order to build the documentation locally you should build and activate the docs environment:

mamba env create -f docs/environment.yml

conda activate gcm-filters-docs

Then navigate to the docs folder and build the docs locally with:

cd docs

make html

Once that is done you can open the created html files in docs/_build/index.html with your webbrowser:

open _build/index.html

You can then edit and rebuild the docs until you are satisfied and submit a PR as usual.