diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 00000000..73a802ed --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,5 @@ +# Developers + +* Barnaby Dobson `b.dobson - at - imperial.ac.uk` +* Taher Chegini +* Diego Alonso Alvarez diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..f1386a79 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +`b.dobson -at- imperial.ac.ak`. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..01728e57 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,139 @@ +# 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. + +```bash +conda create --name swmmanywhere python=3.10 +conda activate 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](https://git-scm.com/downloads) or +with `conda install git`, if you use `conda`. + +```bash +git clone https://github.com/ImperialCollegeLondon/SWMManywhere.git +cd swmmanywhere +``` + +We use [`pip-tools`](https://pip-tools.readthedocs.io/en/latest/) 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: + +```bash +pip install -r dev-requirements.txt +pip install -e . +``` + +## 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`](https://docs.astral.sh/ruff/), +[`markdownlint`](https://github.com/igorshubovych/markdownlint-cli), +[`mypy`](https://github.com/pre-commit/mirrors-mypy), +[`refurb`](https://github.com/dosisod/refurb), +[`codespell`](https://github.com/codespell-project/codespell), +[`pyproject-fmt`](https://github.com/tox-dev/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: + +```bash +pre-commit run --all-files +``` + +`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: + +```bash +pre-commit install +``` + +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: + +```bash +pytest # run all tests +pytest tests/test_file.py # run a specific file's tests +``` + +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: + +```bash +pytest tests/tests_prepare_data.py -m downloads +``` + +You can check the coverage for these tests by running: + +```bash +coverage run -m pytest +coverage report +``` + +And generate a new coverage html for the documentation with + +```bash +coverage html +``` + +## Changing dependencies + +Is 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 then run `pip-compile` as required to regenerate the different +`requirements.txt` files. Read the +[`pip-tools` documentation](https://pip-tools.readthedocs.io/en/latest/) for +more information on the process. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..c7ea631c --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2022, barneydobson +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/swmmanywhere/HISTORY.md b/swmmanywhere/HISTORY.md new file mode 100644 index 00000000..9fbc74fe --- /dev/null +++ b/swmmanywhere/HISTORY.md @@ -0,0 +1,5 @@ +# History + +## 0.1.0 (date) + +- First release goes here