Skip to content

Latest commit

 

History

History
162 lines (111 loc) · 9.26 KB

CONTRIBUTING.md

File metadata and controls

162 lines (111 loc) · 9.26 KB
Raw

Contributing to eo-learn

First of all, thank you for contributing to eo-learn. Any effort in contributing to the library is very much appreciated.

Here is how you can contribute:

All contributors agree to follow our Code of Conduct.

eo-learn is distributed under the MIT license. When contributing code to the library, you agree to its terms and conditions. If you would like to keep parts of your contribution private, you can contact us to discuss about the best solution.

For any question, feel free to contact us at eoresearch@sinergise.com or through our Forum.

Bug Reports

We strive to provide high-quality working code, but bugs happen nevertheless.

When reporting a bug, please check here whether the bug was already reported. If not, open an issue with the bug label and report the following information:

  • Issue description
  • How to reproduce the issue
  • Expected outcome
  • Actual outcome
  • OS and package versions

This information helps us to reproduce, pinpoint, and fix the reported issue.

If you are not sure whether the odd behaviour is a bug or a feature, best to open an issue and clarify.

Feature Requests

Existing feature requests can be found here.

A new feature request can be created by opening a new issue with the enhancement label, and describing how the feature would benefit the eo-learn community. Providing an example use-case would help assessing the scope of the feature request.

Pull Requests

The GitHub Pull Request (PR) mechanism is the best option to contribute code to the library. Users can fork the repository, make their contribution to their local fork and create a PR to add those changes to the codebase. GitHub provides excellent tutorials on how the fork and pull mechanism work, and on how to best create a PR.

Existing PRs can be found here. Before creating new PRs, you should check whether someone else has contributed a similar feature, and if so, you can add your input to the existing code review.

The following guidelines should be observed when creating a PR.

General guidelines

  • Where applicable, create your contribution in a new branch of your fork based on the develop branch, as the master branch is aligned to the released package on PyPI. Upon completion of the code review, the branch will be merged into develop and, at the next package release, into master.

  • Document your PR to help maintainers understand and review your contribution. The PR should include:

    • Description of contribution;
    • Required testing;
    • Link to issue/feature request.

  • Your contribution should include unit tests, to test correct behaviour of the new feature and to lower the maintenance effort. Bug fixes as well as new features should include unit tests. When submitting the PR, check whether the Travis CI testing returns any errors, and if it does, please try to fix the issues causing failure. A test EOPatch is made available here with data for each FeatureType. Unit tests evaluating the correctness of new tasks should use data available in this EOPatch. New fields useful for testing purposes can be added, but should be consistent with the bbox and timestamp of the EOPatch. To execute all unit tests locally on you machine, use the command: pytest from the main folder. See also the examples/README.md for how to setup you SentinelHub account and local config for testing.

  • Try to keep contributions small, as this speeds up the reviewing process. In the case of large contributions, e.g. a new complex EOTask, it's best to contact us first to review the scope of the contribution.

  • Keep API compatibility in mind, in particular when contributing a new EOTask. In general, all new tasks should adhere to the modularity of eo-learn. Check the Section below for more information on how to contribute an EOTask.

  • New features or tasks should be appropriately commented using Sphinx style docstrings. The documentation uses the PEP-8 formatting guidelines. Pylint is used to check the coding standard. Therefore, please run pylint */ *.py from the the main folder, which contains the pylintrc file, to make sure your contribution is scored 10.0/10.0.

Development environment

  • Get the latest development version by creating a fork and clone the repo:
git clone git@github.com:<username>/eo-learn.git

  • Make sure that you have python 3 installed, i.e. version 3.5 or higher. See Python downloads for general Python versions or Anaconda distributions for using Conda.

  • All eo-learn packages can be installed at once using python install_all.py -e. To install each package separately, run pip install -e <package_folder>. We strongly recommend initializing a virtual environment before installing the required packages. For example by using Python Package Index (PyPI) and virtualenv:

cd eo-learn
# The following creates the virtual environment in the ".env" folder.
virtualenv --python python3 .env
source .env/bin/activate

# The following installs all eo-learn subpackages and development packages
# using PyPI in the activated virtualenv environment.
python install_all.py -e
pip install -r requirements-dev.txt -r requirements-docs.txt

Or alternatively by using Conda:

cd eo-learn
# The following creates the virtual environment named "dev_eolearn" where the
# Conda installation in located. ipykernel enables Jupyter (using
# nb_conda_kernels) to select the environment as a kernel. ipywidgets enables
# Jupyter to show the progress bar of EOExecutor without raising an error.
conda create -n dev_eolearn python=3.7 ipykernel ipywidgets
conda activate dev_eolearn

# The following installs all eo-learn subpackages and development packages
# using PyPI in the activated Conda environment.
python install_all.py -e
pip install -r requirements-dev.txt -r requirements-docs.txt

Note: to reduce later merge conflicts, always pull the latest version of the develop branch from the upstream eo-learn repository (located here) to your fork before starting the work on your PR.

Contribute an EOTask

EOTasks allow to apply eo-learn workflows to different use-cases, adapting to imaging sources and processing chain. If you think a task is general enough to be useful to the community, then we would be delighted to include it into the library.

EOTasks are currently grouped by scope, e.g. core, IO, masks, and so on. A list of implemented tasks can be found in the documentation. The following code snippet shows how to create your own EOTask

class FooTask(EOTask):
    def __init__(self, foo_params):
        self.foo_params = foo_params

    def execute(self, eopatch, *, runtime_params):
        # do what foo does on input eopatch and return it
        return eopatch

When creating a new task, bear in mind the following:

  • Tasks should be as modular as possible, facilitating task re-use and sharing.
  • An EOTask should perform a well-defined operation on the input eopatch(es). If the operation could be split into atomic sub-operations that could be used separately, then consider splitting the task into multiple tasks. Similarly, if tasks share the bulk of the implementation but differ in a minority of implementation, consider using Base classes and inheritance. The interpolation tasks represent a good example of this.
  • Tasks should be as generalizable as possible, therefore hard-coding of task parameters or EOPatch feature types should be avoided. Use the EOTask._parse_features method to parse input features in a task, and pass task parameters as arguments, either in the constructor, or at run-time.
  • If in doubt on whether a task is general enough to be of interest to the community, or you are not sure to which sub-package to contribute your task to, send us an email or open a feature request.

Looking forward to include your contributions into eo-learn.