=================
Developers' guide
=================

These instructions are for developing on a Unix-like platform, e.g. Linux or
Mac OS X, with the bash shell.


Requirements
------------

    * Python_ 2.6 and/or 2.7
    * Django_ >= 1.4
    * django-tagging_ >= 0.3
    * parameters >= 0.2.1
    * nose_ >= 0.11.4
    * if using Python 2.6, unittest2_ >= 0.5.1
    * (optional) mpi4py_ >= 1.2.2
    * (optional) twill_ >= 0.9 (for testing web interface)
    * (optional) coverage_ >= 3.3.1 (for measuring test coverage)
    
.. can setup.py install all these?

We strongly recommend developing within a virtualenv_.

Getting the source code
-----------------------

We use the Mercurial version control system. To get a copy of the code you
should fork the main `Sumatra repository on Bitbucket`_, then clone your own fork.::

    $ cd /some/directory
    $ hg clone https://bitbucket.org/<username>/sumatra sumatra_src

If you get an ``SSL3_GET_SERVER_CERTIFICATE`` error, you can either use the
:option:`--insecure` option to :command:`hg clone`, or add the following lines
to your :file:`~/.hgrc` file::

  [hostfingerprints]
  bitbucket.org = 45:ad:ae:1a:cf:0e:73:47:06:07:e0:88:f5:cc:10:e5:fa:1c:f7:99

.. note:: this is the fingerprint used by BitBucket at the time of writing. You
          can get the latest one by visiting the site with a web browser and
          inspecting the certificate (look for the SHA1 fingerprint).

Now you need to make sure that the ``sumatra`` package is on your PYTHONPATH and
that the ``smt`` and ``smtweb`` scripts are on your PATH. You can do this either
by installing Sumatra::

    $ cd sumatra_src
    $ python setup.py install

(if you do this, you will have to re-run ``setup.py install`` any time you make
changes to the code) *or* by installing using ``pip`` with the "editable" option::

    $ pip install --editable sumatra_src

To update to the latest version from the repository::

    $ hg pull -u

.. note:: Please do not use Mercurial branches, use bookmarks instead (these are the
          closest equivalent to Git branches).

Running the test suite
----------------------

Before you make any changes, run the test suite to make sure all the tests pass
on your system::

    $ cd sumatra_src/test/unittests
    $ nosetests

You will see some error messages, but don't worry - these are just tests of
Sumatra's error handling. At the end, if you see "OK", then all the tests
passed, otherwise it will report how many tests failed or produced errors.

If any of the tests fail, check out the `continuous integration server`_ to see
if these are "known" failures, otherwise please `open a bug report`_.

(many thanks to the `NEST Initiative`_ for hosting the CI server).


Writing tests
-------------

You should try to write automated tests for any new code that you add. If you
have found a bug and want to fix it, first write a test that isolates the bug
(and that therefore fails with the existing codebase). Then apply your fix and
check that the test now passes.

To see how well the tests cover the code base, run::

    $ nosetests --coverage --cover-package=sumatra --cover-erase


Committing your changes
-----------------------

Once you are happy with your changes, you can commit them to your local copy of
the repository::

    $ hg commit -m 'informative commit message'
    
and then push them to your Bitbucket repository::

    $ hg push

Before pushing, run the test suite again to check that you have not introduced any new bugs.

Once you are ready for your work to be merged into the main Sumatra repository, please open a pull request.



Coding standards and style
--------------------------

All code should conform as much as possible to `PEP 8`_, and should run with
Python 2.6 and 2.7.

.. _Python: http://www.python.org
.. _Django: https://www.djangoproject.com/
.. _django-tagging: http://code.google.com/p/django-tagging/
.. _nose: https://nose.readthedocs.org/en/latest/
.. _unittest2: http://pypi.python.org/pypi/unittest2
.. _Distribute: http://pypi.python.org/pypi/distribute
.. _mpi4py: http://mpi4py.scipy.org/
.. _tox: http://codespeak.net/tox/
.. _twill: http://twill.idyll.org/
.. _coverage: http://nedbatchelder.com/code/coverage/
.. _`PEP 8`: http://www.python.org/dev/peps/pep-0008/
.. _`issue tracker`: https://bitbucket.org/apdavison/sumatra/issues
.. _virtualenv: http://www.virtualenv.org
.. _`Sumatra repository on Bitbucket`: https://bitbucket.org/apdavison/sumatra
.. _`continuous integration server`: https://qa.nest-initiative.org/view/Sumatra/job/sumatra/
.. _`NEST Initiative`: http://www.nest-initiative.org/
.. _`open a bug report`: https://bitbucket.org/apdavison/sumatra/issues/new