<commit_before>.. _develop:

Developer guide
===============

Getting started
---------------

The first thing you'll need is a `Github <http://github.com/>`__ account.
You can sign up for free.
If you are an academic or student,
`request a free pro-account <https://education.github.com/>`__ to get access to
private repositories.

.. tip::

    The easiest way to contribute is to
    `submit issues and bug reports
    <https://github.com/fatiando/fatiando/issues>`__.
    Feature requests, typo fixes, suggestions for the documentation, it's all
    welcome!

.. note::

    If you are new to **version control** (or don't know what that means),
    start with the `Software Carpentry lessons on version control
    <http://software-carpentry.org/v5/novice/git/index.html>`__.
    After you've gone through those, the
    Github `help page <https://help.github.com/>`__
    and `guides <https://guides.github.com/>`__
    are great resources for finding your way around the quirks of git and
    Github.

All of the "official" code for Fatiando lives in the
`fatiando/fatiando repository <https://github.com/fatiando/fatiando>`__
(the first ``fatiando`` refers to the
`fatiando Github account <https://github.com/fatiando>`__).
The *master* branch of the repository contains the latest code that is
**stable** (should have tested and working code).
Code that is in `other branches
<https://github.com/fatiando/fatiando/branches>`__
are things that are under development by the
`main developers <https://github.com/fatiando/fatiando/graphs/contributors>`__.

To contribute some code/fix/documentation, start by
`forking fatiando/fatiando <https://github.com/fatiando/fatiando/fork>`__
(click the "Fork" button).
This will grab a complete copy of the code repository and add it to your
account.
This "fork" is isolated from the main repository, so you don't have to worry
about "breaking" anything.
Go nuts!
If you break your fork beyond repair you can always delete it and make a new
fork.
Beware that you will lose **everything** in your fork if you delete it.

Once you have your fork, clone a copy to your computer::

    git clone https://github.com/USERNAME/fatiando.git

.. note::

    Not sure what to work on? Have a look at the
    `open issues <https://github.com/fatiando/fatiando/issues>`__
    and pick one that you find interesting.
    **Please leave a comment on the issue if you are going to work on it**.
    This helps us keep track of who is doing what and avoid duplicated work.
    We are trying to curate a
    `list of "low-hanging fruit"
    <https://github.com/fatiando/fatiando/issues?q=is%3Aopen+is%3Aissue+label%3A%22low-hanging+fruit%22>`__
    that are suitable for new-comers.
    Note that "low-hanging" does not necessarily mean trivial,
    but that it doesn't require extensive knowledge of the project.
    **Helping by writing/reviewing/improving the documentation is VERY
    appreciated**. We welcome even the simplest typo fix!

Setting up
----------

Once you have your fork and local clone, you should add it to your
``PYTHONPATH`` environment variable so that you can ``import fatiando``
directly from the source (without installing it).

First, make sure you have uninstalled Fatiando::

    pip uninstall fatiando

In GNU/Linux (or MacOS), add the following lines to your ``~/.bashrc`` file::

    export PYTHONPATH=path/to/fatiando/repository:$PYTHONPATH

In Windows,
create a ``PYTHONPATH`` variable and set it to the path to the ``fatiando``
repository (e.g., ``C:\Documents\User\repos\fatiando``).
Follow
`this guide <http://www.computerhope.com/issues/ch000549.htm>`__
for instructions on setting environment variables.

You will need some extra dependencies installed for development.
If you are using Anaconda (and you should) run::

    conda install cython sphinx nose

and::

    pip install coverage pep8 sphinx-rtd-theme

You will also need `make <http://www.gnu.org/software/make/>`__, which usually
comes with GNU/Linux by default. On windows, you can get it through
`msysGit <http://msysgit.github.io/>`__.
**Don't use the first "Download" button**.
That will get you "Git for Windows".
What you want is "msysGit" (download link at the bottom of the page).
That will give you a
`bash shell <http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29>`__,
git, and make.


Building
--------

The `Makefile <https://github.com/fatiando/fatiando/blob/master/Makefile>`__
contains all the commands for building the C extensions, testing, checking code<commit_msg>Devel docs say install using requirement files<commit_after>.. _develop:

Developer guide
===============

Getting started
---------------

The first thing you'll need is a `Github <http://github.com/>`__ account.
You can sign up for free.
If you are an academic or student,
`request a free pro-account <https://education.github.com/>`__ to get access to
private repositories.

.. tip::

    The easiest way to contribute is to
    `submit issues and bug reports
    <https://github.com/fatiando/fatiando/issues>`__.
    Feature requests, typo fixes, suggestions for the documentation, it's all
    welcome!

.. note::

    If you are new to **version control** (or don't know what that means),
    start with the `Software Carpentry lessons on version control
    <http://software-carpentry.org/v5/novice/git/index.html>`__.
    After you've gone through those, the
    Github `help page <https://help.github.com/>`__
    and `guides <https://guides.github.com/>`__
    are great resources for finding your way around the quirks of git and
    Github.

All of the "official" code for Fatiando lives in the
`fatiando/fatiando repository <https://github.com/fatiando/fatiando>`__
(the first ``fatiando`` refers to the
`fatiando Github account <https://github.com/fatiando>`__).
The *master* branch of the repository contains the latest code that is
**stable** (should have tested and working code).
Code that is in `other branches
<https://github.com/fatiando/fatiando/branches>`__
are things that are under development by the
`main developers <https://github.com/fatiando/fatiando/graphs/contributors>`__.

To contribute some code/fix/documentation, start by
`forking fatiando/fatiando <https://github.com/fatiando/fatiando/fork>`__
(click the "Fork" button).
This will grab a complete copy of the code repository and add it to your
account.
This "fork" is isolated from the main repository, so you don't have to worry
about "breaking" anything.
Go nuts!
If you break your fork beyond repair you can always delete it and make a new
fork.
Beware that you will lose **everything** in your fork if you delete it.

Once you have your fork, clone a copy to your computer::

    git clone https://github.com/USERNAME/fatiando.git

.. note::

    Not sure what to work on? Have a look at the
    `open issues <https://github.com/fatiando/fatiando/issues>`__
    and pick one that you find interesting.
    **Please leave a comment on the issue if you are going to work on it**.
    This helps us keep track of who is doing what and avoid duplicated work.
    We are trying to curate a
    `list of "low-hanging fruit"
    <https://github.com/fatiando/fatiando/issues?q=is%3Aopen+is%3Aissue+label%3A%22low-hanging+fruit%22>`__
    that are suitable for new-comers.
    Note that "low-hanging" does not necessarily mean trivial,
    but that it doesn't require extensive knowledge of the project.
    **Helping by writing/reviewing/improving the documentation is VERY
    appreciated**. We welcome even the simplest typo fix!

Setting up
----------

Once you have your fork and local clone, you should add it to your
``PYTHONPATH`` environment variable so that you can ``import fatiando``
directly from the source (without installing it).

First, make sure you have uninstalled Fatiando::

    pip uninstall fatiando

In GNU/Linux (or MacOS), add the following lines to your ``~/.bashrc`` file::

    export PYTHONPATH=path/to/fatiando/repository:$PYTHONPATH

In Windows,
create a ``PYTHONPATH`` variable and set it to the path to the ``fatiando``
repository (e.g., ``C:\Documents\User\repos\fatiando``).
Follow
`this guide <http://www.computerhope.com/issues/ch000549.htm>`__
for instructions on setting environment variables.

You will need some extra dependencies installed for development.
If you are using Anaconda (and you should) run the following from the
repository base directory::

    conda install --file test/requirements-conda.txt

and::

    pip install -r test/requirements-pip.txt

You will also need `make <http://www.gnu.org/software/make/>`__, which usually
comes with GNU/Linux by default. On windows, you can get it through
`msysGit <http://msysgit.github.io/>`__.
**Don't use the first "Download" button**.
That will get you "Git for Windows".
What you want is "msysGit" (download link at the bottom of the page).
That will give you a
`bash shell <http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29>`__,
git, and make.


Building
--------

The `Makefile <https://github.com/fatiando/fatiando/blob/master/Makefile>`__
contains all the commands for building the C extensions, testing, checking code
{'fraction_non_alphanumeric': 0.10486522024983563, 'fraction_numerical': 0.004054350208196362, 'mean_word_length': 3.8885913229780398, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 26, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '57606', 'n_tokens_mistral': 2791, 'n_tokens_neox': 2634, 'n_words': 1122}