.. _developers:

Developing `smif`
=================

*smif* is under active development at `github.com/nismod/smif`_


Testing
-------

We use `pytest`_ for testing, with tests under :code:`tests/` matching the module
and class structure of :code:`smif/`.

Install requirements for testing::

    pip install -r test-requirements.txt


Run tests::

    python setup.py test


Versioning
----------

:code:`smif` is currently pre-1.0, so API and usage are liable to change. After
releasing a first major version, we intend to follow `semantic versioning`_, with
major versions for any incompatible changes to the public API.


Releases
--------

`smif`_ is deployed as a package on the Python Package Index, PyPI. A full guide
to `packaging`_ and distributing projects is available online.

Deployment to PyPI is handled by Travis CI.

To make a release, create an annotated tag, and submit a pull request::

    git tag -a v0.2.0       # create annotated tag (will need a message)
    git describe            # show current commit in relation to tags

You'll need to specify you tag to push either using the ``--tags`` flag or
the tag name::

    git push upstream master --tags
    git push upstream v0.2.0        # alternatively


Conventions
-----------

The `numpydoc`_ docstring conventions are used for inline documentation, which
is used to generate the module reference documentation visible at `readthedocs`_
and which can also be generated by running ``python setup.py docs``

Linting is handled by `pre-commit`_ hooks, which can be installed from the root
of the repository using::

    pre-commit install


Module import relationship diagram
----------------------------------

.. image:: uml/packages_smif.png
    :alt: smif module/submodule diagram
    :target: _images/packages_smif.png


Class diagrams
--------------

.. image:: uml/classes_smif.png
    :alt: smif class diagram
    :target: _images/classes_smif.png

Decision - simulation class interaction/interface design
--------------------------------------------------------

.. image:: uml/decision-simulation.png
    :alt: UML for smif decision and simulation interaction
    :target: _images/decision-simulation.png


.. _packaging: https://packaging.python.org/distributing/
.. _github.com/nismod/smif: https://github.com/nismod/smif
.. _pytest: http://doc.pytest.org/en/latest/
.. _semantic versioning: http://semver.org/
.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _readthedocs: http://smif.readthedocs.io/en/latest/
.. _pre-commit: http://pre-commit.com/
.. _PyPI: https://pypi.python.org/pypi
.. _smif: https://pypi.python.org/pypi/smif