πŸš€ 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 miniconda to set up python with the following steps:

  • Download the latest miniconda installer and install

  • Open anaconda prompt (or normal terminal on linux)

  • Install mamba with
    conda install -c conda-forge mamba
  • Create a development environment from the eomaps.yml file with
    mamba env create -f < path to eomaps.yml >

Content of eomaps.yml:

name: eomaps
channels:
  - conda-forge

dependencies:
  - python = 3.10
  - numpy
  - scipy
  - pandas
  - geopandas
  - matplotlib >=3.4
  - cartopy >=0.20.0
  - descartes
  - mapclassify
  - pyproj
  - pyepsg
  # --------------for data-shading
  - datashader
  # --------------for GeoTIFF and NetCDF files
  - netcdf4
  - xarray
  - rioxarray
  # --------------for WebMaps
  - owslib
  - requests
  - xmltodict
  - cairosvg
  # --------------for testing
  - coveralls
  - pytest
  - pytest-cov
  # --------------for version control
  - git
  - pre-commit
  # --------------for building the docs
  - sphinx-copybutton
  - sphinx
  - docutils
  - pip
  - pip:
    - sphinx_rtd_theme

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

Pre-commit hooks

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

  • Trailing spaces in .py files

  • Compliance to the used black code formatting standards

To initialize pre-commit hooks in your current environment, navigate to the directory where you cloned the EOmaps repository and run the following command: (e.g. the parent directory containing the file .pre-commit-config.yaml)

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)

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.

  • 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

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

πŸ“– Building the docs

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)

As editor for the docs I recommend the nice free and open-source editor retext. It provides syntax-highlighting for ReStructuredText and a useful table-edit mode.