Skip to content

Latest commit

 

History

History
184 lines (124 loc) · 5.61 KB

CONTRIBUTING.rst

File metadata and controls

184 lines (124 loc) · 5.61 KB
Raw

Contributing

Welcome to the IHE WaterAccounting Engine Tool (IHEWAengine) project. Here's how we work.

Code of Conduct

First of all: the IHEWAengine project has a code of conduct. Please read the CODE_OF_CONDUCT.txt file, it's important to all of us.

Rights

The GNU General Public License v3.0 license (see LICENSE.rst) applies to all contributions.

Issue Conventions

The IHEWAengine issue tracker is for actionable issues.

Questions about installation, distribution, and usage should be taken to the project's wateraccounting.slack.com#issue. Opened issues which fall into one of these three categories may be perfunctorily closed.

Questions about development of IHEWAengine, brainstorming, requests for comment, and not-yet-actionable proposals are welcome in the project's wateraccounting.slack.com#idea.

IHEWAengine is a relatively new project and highly active. We have bugs, both known and unknown.

Please search existing issues, open and closed, before creating a new one.

IHEWAengine employs Geospatial modules, so bug reports very often hinge on the following details:

  • Operating system type and version (Windows? Ubuntu 12.04? 14.04?)
  • The version and source of GDAL (UbuntuGIS? Homebrew?)

Dataset Objects

Our term for the kind of object that allows read and write access to raster data is dataset object. A dataset object might be an instance of DatasetReader or DatasetWriter. The canonical way to create a dataset object is by using the IHEWAengine.GIS.OpenAsArray() function.

This is analogous to Python's use of file object.

Git Conventions

We use a variant of centralized workflow described in the Git Book. We have no 1.0 release for IHEWAengine yet and we are tagging and releasing from the master branch. Our post-1.0 workflow is to be decided.

Work on features in a new branch of the mapbox/IHEWAengine repo or in a branch on a fork. Create a GitHub pull request when the changes are ready for review. We recommend creating a pull request as early as possible to give other developers a heads up and to provide an opportunity for valuable early feedback.

Code Conventions

IHEWAengine supports Python 2 and Python 3 in the same code base, which is aided by an internal compatibility module named compat.py. It functions similarly to the more widely known six but we only use a small portion of the features so it eliminates a dependency.

We strongly prefer code adhering to PEP8.

Tests are mandatory for new features. We use pytest.

We aspire to 100% coverage for Python modules Coveralls.

Development Environment

Developing IHEWAengine requires Python 2.7 or any final release after and including 3.4. We prefer developing with the most recent version of Python but recognize this is not possible for all contributors. See the Windows install instructions in the readme for more information about building on Windows.

Initial Setup

First, clone IHEWAengine's git repo:

$ git clone https://github.com/wateraccounting/ihewaengine.git

Development should occur within a virtual environment to better isolate development work from custom environments.

In some cases installing a library with an accompanying executable inside a virtual environment causes the shell to initially look outside the environment for the executable. If this occurs try deactivating and reactivating the environment.

Installing GDAL

The GDAL library and its headers are required to build IHEWAengine. We do not have currently have guidance for any platforms other than Linux and OS X.

On Linux, GDAL and its headers should be available through your distro's package manager. For Ubuntu the commands are:

$ sudo add-apt-repository ppa:ubuntugis/ppa
$ sudo apt-get update
$ sudo apt-get install gdal-bin libgdal-dev

On OS X, Homebrew is a reliable way to get GDAL.

$ brew install gdal

Python build requirements

Provision a virtualenv with IHEWAengine's build requirements. IHEWAengine's setup.py script will not run unless Cython and Numpy are installed, so do this first from the IHEWAengine repo directory.

Linux users may need to install some additional Numpy dependencies:

$ sudo apt-get install libatlas-dev libatlas-base-dev gfortran

then:

$ pip install -U pip
$ pip install -r requirements-dev.txt

Installing IHEWAengine

Installing IHEWAengine in editable mode while developing is very convenient but only affects the Python files.

$ python setup.py install

Uninstalling IHEWAengine

$ pip uninstall IHEWAengine

Running the tests

IHEWAengine's tests live in python setup.py test and generally match the main package layout.

To run the entire suite and the code coverage engine:

$ python setup.py test