πŸš€ Contribution Guide

πŸ‘· Get in touch

Hey! Nice to see that you’re interested in contributing to EOmaps!

If you need help to get started or got some questions, open a new Issue on GitHub, start a Discussion on GitHub or post a message on gitter and I’ll see what I can do!

Any contributions are welcome!

  • New feature implementations (or ideas for new features)

  • Enhancements for existing features

  • Bug-fixes, code-style improvements, unittests etc.

  • Documentation updates

  • Outreach (e.g. blog-posts, tutorials, talks … )

  • …

Getting started

The source code of EOmaps is managed on GitHub.

To get started, create a new fork of the EOmaps repository to get your own copy of the source code.

Then, open a terminal, navigate to the folder you want to work in and clone the forked repository via:

git clone < link to your fork of the EOmaps repository >

For development, make sure that you first checkout the dev branch which contains all pending changes for the next release. Then, create a new feature or bug-fix branch and start coding!

git checkout dev
git checkout -b "awesome_new_feature"

Once you’re done or in case you want/need some feedback, open a pull request on GitHub!

How to set up a development environment

To contribute to EOmaps, you need a working python installation.

I recommend using miniforge, a minimalistic installer that contains the package-managers conda and mamba already pre-configured to use the conda-forge channel by default.

You can set up python with the following steps:

  • Download the latest miniforge installer and install

  • On Windows, miniforge is not added to the system path by default. To use conda/mamba, open Miniforge Prompt! For Linux and OS X you should be able to use the normal command prompt.

  • Create a new development environment from the eomaps/environment.yml file with
    mamba env create -f < path to environment.yml >

Content of environment.yml:

name: eomaps
channels:
  - conda-forge

dependencies:
  - python >= 3.8
  - numpy
  - scipy
  - matplotlib >=3.4
  - cartopy >=0.20.0
  - descartes
  # ------------- to handle data-classification
  - mapclassify
  # ------------- to handle reprojections
  - pyproj
  # ------------- to support Dataframes
  - pandas
  # ------------- to support GeoDataFrames
  - geopandas
  # --------------for data-shading
  - datashader
  # --------------for GeoTIFF and NetCDF files
  - netcdf4
  - xarray
  - rioxarray
  # --------------for WebMaps
  - owslib
  - requests
  # --------------to support multiple Qt versions
  - qtpy
  # --------------for jupyter widgets
  - ipywidgets
  - ipympl

  ### To run the tests
  - coveralls
  - pytest
  - pytest-cov
  - pytest-mpl
  # --------------for testing the docs
  # (e.g. parsing .rst code-blocks and Jupyter Notebooks)
  - docutils
  - jupyter
  - nbformat

  ### To build the docs
  - docutils
  - sphinx
  - sphinx-copybutton
  - sphinx-design
  - sphinx_rtd_theme
  - myst-nb

Tip

As editor, I recommend using the awesome, free and open-source Spyder IDE. You can install it directly into your environment via:

mamba install -c conda-forge spyder

Development Practices

This section provides a guide to how we conduct development in the EOmaps repository. Please follow the practices outlined here when contributing directly to this repository.

Testing

After making changes, please test changes locally before creating a pull request. The following tests will be executed after any commit or pull request, so we ask that you perform the following sequence locally to track down any new issues from your changes.

The environment.yml file already contains the packages required to run the tests locally, e.g.:

To run the primary test suite and generate coverage report, navigate to the parent eomaps directory and run:

python -m pytest -v --cov eomaps --mpl

Some of the tests compare exported images with a set of baseline-images to ensure stable image exports and to catch potential issues that are not detected by the code based tests.

If changes require an update of the baseline images, you have to invoke pytest-mpl with the mpl-generate-path option:

python -m pytest -v --cov eomaps --mpl --mpl-generate-path=tests/baseline

This will update all images in the tests/baseline folder.

Note

During the tests, a lot of figures will be created and destroyed!

Before updating new baseline images, make sure to manually check that they look exactly as expected!

Tip

You can run only a subset of the tests by using the -k flag! (This will select only tests whose names contain the provided keyword)

python -m pytest -k <QUERY KEYWORD>

(see pytest command-line-flags for more details)

Tip

Unit testing can take some time, if you wish to speed it up, you can install pytest-xdist to leverage multiple processes with the -n flag.

python -m pytest -n <NUMBER OF CORES>

Style Checking

To ensure uniform code style, EOmaps uses pre-commit hooks to automatically check (and fix) code-style issues such as:

  • Removal of trailing whitespaces in .py files

  • Making sure that files end with a newline

  • Compliance to the used black code formatting standards

To initialize pre-commit hooks in your current environment, first install pre-commit hooks with

mamba install -c conda-forge pre-commit

Then navigate to the directory where you cloned the EOmaps repository and run the following command: (e.g. the directory that contains the .pre-commit-config.yaml file)

pre-commit install

This will install the required pre-commit hooks in your current environment so that they are run automatically prior to each commit. (The first time pre-commit is run, the necessary packages will have to be installed which might take a short moment)

git commit -m "added my cool feature"

check python ast.........................................................Passed
check for merge conflicts................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
mixed line ending........................................................Passed
black....................................................................Passed

Note

This means that all files will be auto-formatted prior to each commit to comply with the used code-formatting standards and only commits that comply with all pre-commit hooks can be pushed to GitHub.

⚠ After running the pre-commit hooks, some files might have new changes that must be staged for commit again!

Tip

  • To run the pre-commit hooks manually on selected files, simply add the files you want to commit with git add < filename > and then run pre-commit

  • If you want to run the hooks on all files, use pre-commit run --all-files

Tip

If you have issues related to setuptools when installing pre-commit, see pre-commit Issue #2178 comment for a potential resolution.

Building the Documentation

The documentation of EOmaps is written with Sphinx using the markup language ReStructuredText.

To build the documentation locally, simply navigate to the folder eomaps/docs and then run

make html

The first time the documentation is built, all auto-generated files parsed from the python-code have to be generated which might take a bit of time. Subsequent calls will be much faster since they only update files that contain changes!

  • Once finished, you will find a new folder in the EOmaps directory (eomaps/docs/build/html) that contains all the source files for the documentation.

  • Open eomaps/docs/build/html/index.html to get to the starting-page!

Automating the build process

Manually re-building the documentation can be tedious… fortunately it is possible to automatically re-build the documentation if a file changed and live-reload the local docs in the browser with the awesome sphinx-autobuild package.

To install, run mamba install -c conda-forge sphinx-autobuild.

After installation, navigate to the eomaps directory and start the automatic build-process with

sphinx-autobuild docs docs/build/html --ignore ["generated/*"] --open-browser

This will trigger a first build of the documentation and start a http server that hosts the local documentation (and live reloads it as soon as the build process finished)

The url of the http-server will be printed to the console (the default is: 127.0.0.1:8000).

Tip

As editor for the docs I recommend the nice minimalistic free and open-source editor retext.

It provides syntax-highlighting and live-preview for both Markdown and ReStructuredText.