How to contribute

The EnMAP-Box is a freely available, platform-independent software designed to process hyperspectral remote sensing data, and particularly developed to handle data from the EnMAP sensor.

The EnMAP-Box source code is hosted in a public git repository at https://bitbucket.org/hu-geomatics/enmap-box.

Approved QGIS plugin versions (“production releases”) are available in the QGIS Plugin Repository https://plugins.qgis.org/plugins/enmap-box.

The development of the EnMAP-Box is funded within the EnMAP scientific preparation program under the DLR Space Administration (mission lead) and GFZ Potsdam (scientific lead) with resources from the German Federal Ministry for Economic Affairs and Energy.

Everyone is welcome to contribute to the EnMAP-Box

Submit a bug report or feature request

In case you experience issues with the EnMAP-Box, do not hesitate to submit a ticket to our Issue Tracker. You are also welcome to post feature requests or pull requests.

It is recommended to check that your issue complies with the following rules before submitting:

  • Verify that your issue is not being currently addressed by other issues or pull requests.

  • If you are submitting a bug report, please:

    • Report a short description how to reproduce it
    • If an exception is raised, please provide the full traceback.
    • If necessary, provide a link to the data that causes the bug
    • If not feasible to include a reproducible snippet, please be specific about what part of the EnMAP-Box (functions, widget) are involved and the shape of the data
    • Include your operating system type and version number of QGIS, Qt and the EnMAP-Box.
    • Please ensure that code snippets and error messages are formatted in appropriate code blocks.

    Note

    You can use this Markdown syntax to style your issues.

Provide source code

If your are not an EnMAP-Box core developer, the preferred way to contribute your code code is to use pull requests.

  1. Fork the EnMAP-Box repository
  2. Clone you fork
  3. Modify the source code
  4. Commit your modifications
  5. Push your modification to your fork and
  6. Create a pull request

1. Create a fork on Bitbucket

Forking the EnMAP-box repository allows you to modify the EnMAP-Box code as you like and backup your contributions on a separated Bitbucket repository

Please read https://confluence.atlassian.com/bitbucket/forking-a-repository-221449527.html for details how you can create your own fork of the EnMAP-Box repository.

2. Clone the forked EnMAP-Box repository

Clone the forked EnMAP-Box repository myfork to your local disk:

$ git clone git@bitbucket.com/myusername/myfork.git
$ cd enmapbox

Now install python requirements and run the initial setup for the EnMAP-Box repository, as described in Installation (Detailed)

Add the EnMAP-Box repository as upstream repository:

$ git remote add upstream https://bitbucket.org/hu-geomatics/enmap-box

Note

From now on, you can synchronize the master branch of your forked repository with the EnMAP-Box repository by:

$ git checkout master
$ git pull upstream master

3. Modify the local repository

Now you can start your own feature branch ‘my_modifications’:

$ git checkout -b my_modifications

4. Commit your changes

Save your changes by committing them to your local repository:

$ git add modified_files
$ git commit -a -m 'added x, modified y and fixed z' -s

Please use signed commits to label your individual contribution visible. Even better, use GnuPG-signed commits (-S).

5. Push changes back to your fork

The pull request informs us on the changes you like to bring into the EnMAP-Box:

$ git push

6. Create a pull request

Open the Bitbucket webpage of your fork and create a pull request. The pull request will inform us on the changed you made.

Before you create a pull request, please check the following:

  • make sure that every source code file provides a licence notice

  • make sure your code passes the tests and provide tests if your like to provide new functionality, like EnMAP-Box Applications

  • make sure your code is commented and documented

  • make sure your name is listed in the CONTRIBUTORS.md

  • update your feature branch to the current EnMAP-Box master branch:

    git fetch origin
    
  • rebase your changes and push them to your forked repository:

    git push -f
    
  • describe your pull request with a helpful title, e.g using the following labels:

    • [feature] <title> a new feature
    • [fix] <title> a fix for a known issue. If possible, please refer to existing issue numbers like in #123 #124.

Documentation

The EnMAP-Box documentation is based on Sphinx-build reStructured text and hosted at https://enmap-box.readthedocs.io . The *.rst files are located in the repositories doc/source folder.

To build and text the documentation on your local system, navigate into the doc folder and run the make file:

$ cd doc
$ make html

This will start Sphinx and create the HTML documentation into folder doc/build. Open doc/build/html/index.html to visualize it in your web browser.

Licensing

The software produced for the EnMAP-Box is licensed according to the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License (SPDX short identifier: GPL-3.0), or (if desired) any later version. See either https://www.gnu.org/licenses/gpl-3.0.en.html or https://opensource.org/licenses/GPL-3.0 for further details of the license.

A copy of this license is part of the EnMAP-Box repository (LICENSE.txt) and delivered with each release of an EnMAP-Box plugin.

The EnMAP-Box documentation is published under the terms of the Creative Commons 1.0 Universal (CC0) License. See https://creativecommons.org/publicdomain/zero/1.0/legalcode for further details of the license.

Each source code contribution to the central repository should include a reference to the GPL-3 license terms at the beginning of the file:

"""
***************************************************************************
    <file name> - <short description>
    -----------------------------------------------------------------------
    begin                : <month and year of creation>
    copyright            : (C) <year> <creator>
    email                : <main address>

***************************************************************************
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.
                                                                                                                                                 *
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this software. If not, see <http://www.gnu.org/licenses/>.
***************************************************************************
"""

An example from the source code can be found here: enmapbox/__init__.py

Note

Todo: add PyCharm code template

Images and other multimedia content from the EnMAP-Box documentation, i.e files within the EnMAP-Box repositories doc/source folder, are published without copyright under the terms of the CC0 license.

The purpose of CLAs are to clearly define the terms under which intellectual property has been contributed to the EnMap-Box and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time.

Individual Contributor License Agreement (ICLA)

The EnMap-Box Consortium desires that all maintainers and contributors of ideas, code, or documentation to the EnMAP-Box project complete, sign, and submit an ICLA.

A signed ICLA is required to be on file before an individual is given commit rights to the EnMap-Box repository. The ICLA form for filling and signing is available at https://www.apache.org/licenses/icla.pdf.

The ICLA is not tied to any employer, so it is recommended to use one’s personal information, e.g. for email address in the contact details, rather than an email address provided by an employer.

Corporate Contributor License Agreement (CCLA)

For a corporation that has assigned employees to work on the EnMap-Box, a CCLA is available for contributing intellectual property via the corporation, that may have been assigned as part of an employment agreement.

Note that a CCLA does not remove the need for every developer to sign their own ICLA as an individual, which covers both contributions which are owned and those that are not owned by the corporation signing the CCLA.

The CCLA legally binds the corporation, so it must be signed by a person with authority to enter into legal contracts on behalf of the corporation. The CCLA form for filling and signing is available at http://www.apache.org/licenses/cla-corporate.pdf.

Submitting License Agreements

Documents may be submitted by email and signed by hand or by electronic signature. The files should be named icla.pdf and icla.pdf.asc for individual agreements; ccla.pdf and ccla.pdf.asc for corporate agreements. Zip files, other archives, or links to files are not accepted. The files must be attached to the mail.

When submitting by email, please fill the form with a pdf viewer, then print, sign, scan all pages into a single pdf file, and attach the pdf file to an email to enmapbox@enmap.org. If possible, send the attachment from the email address in the document. Please send only one document per email.

If you prefer to sign electronically, please fill the form, save it locally (e.g. icla.pdf), and sign the file by preparing a detached PGP signature. For example, gpg –armor –detach-sign icla.pdf

The above will create a file icla.pdf.asc. Send both the file (icla.pdf) and signature (icla.pdf.asc) as attachments in the same email. Please send only one document (file plus signature) per email. Please do not submit your public key. Instead, please upload your public key to pgpkeys.mit.edu.

Developer Certificate of Origin (DCO)

Contributors who have not signed an ICLA are in a somewhat fuzzy spot. If they make a large contribution, or many contributions, then the EnMap-Box maintainers will likely ask to submit an ICLA. However, for small fixes, infrequent and other minimal or sporadic contributions the terms for licensing and intellectual property still must be clarified.

For this purpose, barriers for contributing are minimized and contributors pinky swear that they’re submitting their own work or rather certify that they adhere to the requirements of the DCO defined in version 1.1 or later at https://developercertificate.org/ by signing-off their pull requests or similar ways of contributing.

The DCO is very Git-centric, and it only relies on commit metadata.

Indeed, signing-off a commit is just about appending a Signed-off-by. For example a commit like:

$ git commit -m 'Fixes issue XYZ' -s

will create a commit message as in:

commit b2c150d3aa82f6583b9aadfecc5f8fa1c74aca09
Fixes issue XYZ
Signed-off-by: Erwin Gerwin <erwin.gerwin@streetcat.com>

Even this approach introduces a low barrier for contributions, it is very easy to use whatever email address you want for a commit, and the sign-off is just text. Since the issue of trust is important the use of GnuPG signatures in Git commits is recommended additionally, e.g. with:

$ git commit -s -S (makes GnuPG-signed commits, and)
$ git log --show-signature (shows GnuPG signatures in the log history)
$ git merge --verify-signatures branch (ensures that all commits are signed and valid before performing a merge)

Having to use GnuPG for all commits can be a bit daunting.

Tests and Continuous Integration

Please provide some tests that show if your source code works right. Unit tests should be located in the repositories enmapboxtesting folder.

To run all tests call:

$ set CI=True
$ python -m nose2 -s enmapboxtesting

Note

The environmental variable CI=True is used to inform test routines to not enter the GUI thread. If unset, some widgets might pop-up and wait for your input to terminate.

To run the unit tests in test_mytests.py, call:

$ python -m nose2 -s enmapboxtesting test_mytests