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

These instructions are for developing on a Unix-like platform, e.g. Linux or
Mac OS.


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

* Python_ 3.9 or later
* Django_ >= 4.2
* django-tagging_
* parameters
* pytest
* docutils
* Jinja2

Optional:

* mpi4py_
* pytest-cov (for measuring test coverage)
* httplib2 (for the remote record store)
* GitPython (for Git support)
* mercurial and hgapi (for Mercurial support)
* bzr (for Bazaar support)
* PyYAML (for YAML support)
* psycopg2 (for PostgreSQL support)
* dexml and fs (for WebDAV support)


We strongly recommend developing within a virtualenv_.

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

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

    $ cd /some/directory
    $ git clone https://github.com/<username>/sumatra.git
    $ cd sumatra

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 normally from the local checkout::

    $ pip install .[dev]

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

    $ pip install --editable .[dev]

To ensure you always have access to the most recent version, add the main repository as "upstream"::

    $ git remote add upstream https://github.com/open-research/sumatra.git

To update to the latest version from the repository::

    $ git pull upstream master


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

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

    $ pytest

You will see some warning 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`_.


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::

    $ pytest --cov=sumatra


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

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

    $ git commit -m 'informative commit message'

and then push them to your Github repository::

    $ git 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.
You are encouraged to use a separate branch for each feature or bug-fix, as it makes merging changes easier.


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

All code should conform as much as possible to `PEP 8`_, and should run with
Python 3.9 or later. Lines should be no longer than 119 characters.


Reviewing pull requests
-----------------------

All contributors are encouraged to review pull requests, and all pull requests must have at least one review before
merging.

Things to check for:

* Does the pull request implement a single, well-defined piece of functionality?
  (pull requests which perform system-wide refactoring are sometimes necessary, but need much more careful scrutiny)
* Does the code work? Is the logic correct? Does it anticipate possible failure conditions (e.g. lack of internet connection)?
* Is the code easily understood?
* Does the code conform to the coding standards (see above)?
* Does the code implement a general solution, or is the code too specific to a particular (language|version control system|storage backend)?
* Do all public functions/classes have docstrings?
* Are there tests for all new/changed functionality?
* Has the documentation been updated?
* Has the GitHub Actions CI build passed?
* Is there any redundant or duplicate code?
* Is the code as modular as possible?
* Is there any commented out code, or print statements used for debugging?


.. _Python: https://www.python.org
.. _Django: https://www.djangoproject.com/
.. _django-tagging: https://github.com/jazzband/django-tagging
.. _pytest: https://docs.pytest.org
.. _Distribute: https://pypi.python.org/pypi/distribute
.. _mpi4py: http://mpi4py.scipy.org/
.. _coverage: http://nedbatchelder.com/code/coverage/
.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
.. _`issue tracker`: https://github.com/open-research/sumatra/issues
.. _virtualenv: http://www.virtualenv.org
.. _`Sumatra repository on Github`: https://github.com/open-research/sumatra
.. _`continuous integration server`: https://github.com/open-research/sumatra/actions
.. _`NEST Initiative`: http://www.nest-initiative.org/
.. _`open a bug report`: https://github.com/open-research/sumatra/issues/new
