.. _develop:

Contributor Guide
=================

Development environment
-----------------------

If you whish to contribute to the development of the code and/or the
documentation, here are a few steps for setting a development environment.

Fork the repository and download the code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To further be able to submit modifications, it is preferable to start by
forking the xarray-topo repository on `GFZ GitLab (ext)`_ (you need to have an
account).

Then clone your fork locally::

  $ git clone https://gitext.gfz-potsdam.de/your_name_here/xarray-topo

Alternatively, if you don't plan to submit any modification, you can clone the
original xarray-topo git repository::

   $ git clone https://gitext.gfz-potsdam.de/sec55-public/xarray-topo

.. _`GFZ GitLab (ext)`: https://gitext.gfz-potsdam.de/

Install
~~~~~~~

To install the dependencies, we recommend using the conda_ package manager with
the conda-forge_ channel. For development purpose, you might consider installing
the packages in a new conda environment::

  $ conda create -n xarray-topo_dev python=3.6 numpy xarray -c conda-forge
  $ source activate xarray-topo_dev

Then install xarray-topo locally using ``pip``::

  $ cd xarray-topo
  $ pip install -e .

.. _conda: http://conda.pydata.org/docs/
.. _conda-forge: https://conda-forge.github.io/

Run tests
~~~~~~~~~

Not yet available!

Contributing to code
--------------------

Below are some useful pieces of information in case you want to contribute
to the code.

Local development
~~~~~~~~~~~~~~~~~

Once you have setup the development environment, the next step is to create
a new git branch for local development::

  $ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

Submit changes
~~~~~~~~~~~~~~

Once you are done with the changes, you can commit your changes to git and
push your branch to your xarray-topo fork on GFZ GitLab::

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature

(note: this operation may be repeated several times).

We you are ready, you can create a new merge request through the GFZ GitLab
website (note that it is still possible to submit changes after your created a
pull request).

Python versions
~~~~~~~~~~~~~~~

xarray-topo supports Python versions 3.4 and higher. It is not compatible
with Python versions 2.x. We don't plan to make it compatible with Python 2.7.x
unless there are very good reasons to do so.

Test
~~~~

Not yet available!

Docstrings
~~~~~~~~~~

Everything (i.e., classes, methods, functions...) that is part of the public API
should follow the numpydoc_ standard when possible.

.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

Coding style
~~~~~~~~~~~~

The xarray-topo code mostly follows the style conventions defined in PEP8_.

.. _PEP8: https://www.python.org/dev/peps/pep-0008/

Source code checker
~~~~~~~~~~~~~~~~~~~

To check about any potential error or bad style in your code, you might want
using a source chode checker like flake8_. You can install it in your
development environment::

  $ conda install flake8 -c conda-forge

.. _flake8: http://flake8.pycqa.org

What's new entry
~~~~~~~~~~~~~~~~

Every significative code contribution should be listed in the
:doc:`whats_new` section of this documentation under the corresponding version.

Contributing to documentation
-----------------------------

xarray-topo uses Sphinx_ for documentation, hosted on http://readthedocs.org .
Documentation is maintained in the RestructuredText markup language (``.rst``
files) in ``xarray-topo/doc``.

To build the documentation locally, first install requirements (for example here
in a separate conda environment)::

   $ conda env create -n xarray-topo_doc -f doc/environment.yml
   $ source activate xarray-topo_doc

Then build documentation with ``make``::

   $ cd doc
   $ make html

The resulting HTML files end up in the ``build/html`` directory.

You can now make edits to rst files and run ``make html`` again to update
the affected pages.

.. _Sphinx: http://www.sphinx-doc.org/