Contributing
============

Thank you for your interest !

Steps for contributing
----------------------

The master branch in the repository houses the code that has been completely
tested and is bug free to the best of our knowledge. If you encounter a
bug in the code, please raise an issue in the repository.

`Instructions on raising an
issue <https://help.github.com/en/articles/creating-an-issue>`__

Addressing a bug fix
--------------------

1. Fork the repository and clone it into your local machine

.. code:: bash

   git clone https://github.com/kLabUM/pystorms
   cd pystorms

2. Create a new branch for the fix

For example, if I am fixing an issue with the pollutant, I would create a
new branch using this command.

.. code:: bash

   git checkout -b abhiramm7_pollutantfix

3. Add your fixes and push the changes into your fork of the repository.

.. code:: bash

   git add <your changed files>
   git push origin abhiramm7_pollutantfix

`More
details <https://help.github.com/en/articles/pushing-to-a-remote>`__

4. Once you are confident in the changes, you can create a pull request on
   the pystorms repository.

`Raising a pull
request <https://help.github.com/en/articles/creating-a-pull-request-from-a-fork>`__

We can then work through the pull request.

Testing
-------

Please create a unit test for the code addition or any contribution you
wish to make to the library. This repository uses ``pytest`` for testing.
Unit tests can be found in ``tests/`` and run with

.. code:: bash

   pip install -e . pytest
   pytest tests

Continuous integration runs the same suite on Linux, macOS and Windows for
every supported Python version on each push to ``master`` and to
``release/**`` branches. Tests keep their derived networks and SWMM run files
in a temporary directory, so they leave nothing behind.

Details on where to include what
--------------------------------

``pystorms/networks``
~~~~~~~~~~~~~~~~~~~~~

This package provides access to the SWMM input files shipped with the
library. To add a network:

1. Add your processed input file (refer to building scenarios on how to
   process your input file) as ``pystorms/networks/<your network>.inp``.
   **Once you add your network to the library, it is public. So please be
   careful about what you upload.**

2. ``load_network("<your network>")`` finds the file by name; nothing else
   has to be registered.

3. Add a test to ``tests/test_networks.py``

.. code:: python

   network = pystorms.networks.load_network("<your network>")
   assert "inp" == network[-3:]

``pystorms/utilities.py``
~~~~~~~~~~~~~~~~~~~~~~~~~

Any **general** function you might need in developing scenarios goes in
``utilities.py``.

For example, we use the ``append_rainfall`` function for adding rainfall
timeseries to input files. This can be used on *any* input file and is
not specific to a particular scenario. Hence, this function lives in
``utilities.py``.

``pystorms/scenarios``
~~~~~~~~~~~~~~~~~~~~~~

One module per scenario, each defining a class of the same name, plus
``scenario.py`` with the base class every scenario derives from. Refer to
building scenarios for more details on how to build one, and import the
new class in ``pystorms/scenarios/__init__.py``.

Anything that is **specific** to a network or scenario goes here. A scenario
that defines a second version builds it inside its constructor and validates
the keyword with ``validate_version``; one that does not should still accept
the keyword and pass ``("1",)`` as the supported versions.

``pystorms/config``
~~~~~~~~~~~~~~~~~~~

The configuration files, holding the network name, the state and action
space and the performance targets, are placed here, one yaml file per
scenario. The ``name`` is used to find both the yaml file and the network.

.. code:: yaml

        # Configuration file for scenario theta

        # name of scenario
        name: theta
        # state definitions
        states:
                - !!python/tuple
                  - P1
                  - depthN
                - !!python/tuple
                  - P2
                  - depthN
        # Action space
        action_space:
                - "1"
                - "2"
        # Performance Targets
        performance_targets:
                - !!python/tuple
                  - "8"
                  - flow
                - !!python/tuple
                  - P1
                  - flooding
                - !!python/tuple
                  - P2
                  - flooding

Add a test that constructs the scenario and runs it to completion to
``tests/test_scenarios.py``, and if it defines a second version, to
``tests/test_versions_and_levels.py`` as well.