Developers’ guide

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

Requirements

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:

$ cd /some/directory
$ hg clone https://neuralensemble.org/hg/sumatra sumatra_src

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

[hostfingerprints]
neuralensemble.org = 7c:a8:72:19:79:b2:ec:d8:27:59:34:dc:a3:13:d9:5e:c3:aa:53:0e

Note

an alternative is to fork the Sumatra mirror on Bitbucket, then clone your own fork.

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 creating symbolic links from somewhere on your PATH and PYTHONPATH, for example:

$ cd /some/directory
$ ln -s sumatra_src/src sumatra
$ export PYTHONPATH=/some/directory:${PYTHONPATH}
$ export PATH=/some/directory/sumatra_src/bin:${PATH}

To update to the latest version from the repository:

$ hg pull -u

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'

If you have a NeuralEnsemble account, you can now push your changes to the central repository:

$ hg push https://neuralensemble.org/hg/sumatra

If you are using Bitbucket, you can open a pull request.

Otherwise, you can create a patch:

$ hg export tip > descriptive_name.patch

and attach it to a ticket in the issue tracker. If you have made more than one commit, determine the revision number of when you cloned or last updated from the central repository (using hg log), and then give a range of revisions to include in the patch:

$ hg export start-revision:tip > descriptive_name.patch

Before either pushing or creating a patch, run the test suite again to check that you have not introduced any new bugs.

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.