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.
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:
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.
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.
- Fork the EnMAP-Box repository
- Clone your fork
- Modify the source code
- Commit your modifications
- Push your modification to your fork and
- 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 in a separated Bitbucket repository. To create a fork,
- log in to bitbucket.org and visit https://bitbucket.org/hu-geomatics/enmap-box
- Click ‘+’ and Fork this repository
- Select a name and workspace for your EnMAP-Box fork, hereafter called enmap-box-fork
Create an EnMAP-Box fork in bitbucket.org
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.
Please note that forking in bitbucket.org does not copy git lfs tracked files: https://support.atlassian.com/bitbucket-cloud/docs/current-limitations-for-git-lfs-with-bitbucket/#Git-LFS-files-are-not-copied-when-a-repo-is-forked
2. Clone the forked EnMAP-Box repository¶
Clone enmap-box-fork to your local disk:
git clone email@example.com/myusername/enmap-box-fork.git -n
You might see some git lfs errors. Ignore them.
Go into the repository folder and force to checkout the develop branch.
cd enmap-box-fork git checkout develop -f
You can ignore smuge errors. Add the EnMAP-Box repository as upstream repository:
git remote add upstream https://bitbucket.org/hu-geomatics/enmap-box
Now fetch git lfs files from the upstream directory:
git lfs fetch upstream
From now on, you can synchronize your fork with the EnMAP-Box repository by:
$git fetch upstream develop $git merge upstream/develop
to get the latest updates from the develop branch. Call:
to upload them to the remote bitbucket.com/myusername/enmap-box-fork.git
Now install python requirements and run the initial setup for the EnMAP-Box repository, as described in Installation
3. Modify the local repository¶
As you like, you can continue modifying the EnMAP-Box code in the develop branch or create a new one ‘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¶
A push will upload your changes to bitbucket.com/myusername/enmap-box-fork.git:
$ 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
update your feature branch to the current EnMAP-Box develop branch:
git fetch upstream develop git merge upstream/develop
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.
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/html/index.html to visualize it in your web browser.
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
Images and other multimedia content from the EnMAP-Box documentation, i.e files within the EnMAP-Box repositories
are published 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 here.
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 here.
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 firstname.lastname@example.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 <email@example.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
To run all tests call:
$ set CI=True $ python -m nose2 -s enmapboxtesting
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