Contributing to SWMManywhere
Thank you for considering contributing to SWMManywhere.
Bugs
Please create a new issues (insert link when published)
if you may have found a bug.
Please describe the bug and instructions on recreating it (including OS and
Python version). Label the issue with bug.
New behaviour
Our intention with SWMManywhere is that a high level of customisation to suit
your needs may be achieved by adding new graphfcns or new metrics, see
below. Other new behaviour may be tagged with enhancement, though please
check existing issues (insert link when published)
to see if something similar already exists.
Take a graph give a graph: graphfcns
All transformations that take place do so on graph functions, you can change
the order in which these are executed and add new ones. If you want a
graphfcn that does a new thing, please create an issue to discuss with the
label graphfcn. If a single new graphfcn is not sufficient to capture the
transformations that you'd like to apply, more may be needed. If this is the
case, please first create an issue labelled with enhancement detailing the
thing that you would like to capture, where we will discuss what graphfcns
are needed, and use this issue to coordinate.
Evaluate against real data with: metrics
We have provided a large set of metrics against which a synthetic graph's
performance may be evaluated if a real network is provided. If you want to
create a new metric, please create an issue to discuss with the label
metric.
Installation for development
To install SWMManywhere in development mode, first you will need a virtual
environment. Here we use a conda environment which let us use the version of
python we want to use, but you can use any other tool you are familiar with.
Just make sure you use a version of Python compatible with SWMManywhere.
Once in the environment, you need to clone the SWMManywhere GitHub repository
locally and move into the right folder. You will need git for that, installed
either following the official instructions or
with conda install git, if you use conda.
We use pip-tools to ensure
consistency in the development process, ensuring all people contributing to
SWMManywhere uses the same versions for all the dependencies, which minimiese
the conflicts. To install the development dependencies and then SWMManywhere
in development mode run:
Quality assurance and linting
SWMManywhere uses a collection of tools that ensure that a specific code
style and formatting is follow throughout the software. The tools we used for
that are ruff,
markdownlint,
mypy,
refurb,
codespell,
pyproject-fmt.
You do not need to run them manually - unless you want to - but rather they are
run automatically every time you make a commit thanks to pre-commit.
If you want to run them manually before committing, you can do so with:
pre-commit should already have been installed when installing the dev
dependencies, if you followed the instructions above, but you need to activate
the hooks that git will run when making a commit. To do that just run:
You can customise the checks that ruff, mypy, and refurb will make with
the settings in pyproject.toml. For markdownlint, you need to edit the
arguments included in the .pre-commit-config.yaml file.
Testing and coverage
SWMManywhere uses pytests as testing suite. You can run tests by navigating
to the folder and running:
By default the tests/tests_prepare_data.py does not test the actual downloads
themselves (since this relies on external APIs actually working at the time of
testing), however downloads can be enabled when testing:
You can check the coverage for these tests by running:
And generate a new coverage html for the documentation with
Changing dependencies
As the development process moves forward you find you need to add a new
dependency, just add it to the relevant section of the pyproject.toml file
and recompile requirements:
pip-compile
pip-compile --extra dev -o dev-requirements.txt pyproject.toml
pip-compile --extra doc -o doc-requirements.txt pyproject.toml
Read the
pip-tools documentation for
more information on the process.