Skip to content

How to Contribute

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and you always earn credits.

You can contribute on the code side in many ways:

  • submit feedback,
  • add new features,
  • report bugs,
  • fix bugs,
  • implement a new cluster/cloud computation backend,
  • write documentation

Code

Linting and pre-commit

For every code contribution, the pre-commit utility should be executed. This will lint, format and check your code contributions against our guidelines (e.g. we use Black as code style and aim for REUSE compliance):

  1. Installation conda install -c conda-forge pre-commit or pip install pre-commit
  2. Usage:
    • To automatically activate pre-commit on every git commit: Run pre-commit install
    • To manually run it: pre-commit run --all

Testing

Add a new test if you want to contribute new functionality to the config. We currently perform multiple integration tests which means various workflows need to work. All test configs are build by updating config.tutorial.yaml with the configs in pypysa-earth/test/*.yaml.

  • You can test your contribution locally with make test.
  • See the Makefile for further information which configurations are tested.

To contribute a test:

  1. Provide a new test in test/<new test>.yaml, or adjust one of the existing ones. These tests update the config.tutorial.yaml to test other options e.g. landlock countries.
  2. Add a new test config path to the rule build_all_test in the Snakefile.
  3. If your functionality should be tested in the CI for every pull request, add a respective code in .github/workflows/ci-linux.yaml. We test all functionalities only for Linux while providing a general test for windows and mac.

Data

A comprehensive set of the databundles has been created by a coordinated work of many people around the world. To improve accuracy and keep the model up-to-date, we highly encourage contribution of new datasets, in particular those which are tailored to the needs of particular regions. Examples of datasets which you can contribute: - cutouts for you region of interest - hourly time-series of electricity demand

To contribute a new dataset, you just need to upload it to some publicly available storage (e.g. Zenodo) and add specification of this dataset to configs/bundle_config.yaml following structure of other specifications. A name of each dataset must be unique, and category specified must be aligned with the other available categories.

If your uploaded dataset is intended for usage in CI testing, a tutorial version must be added as well.

Documentation

How to docs?

We add the documentation continuously while the project grows, which makes it easier to understand and maintain for you and the whole community. We rely on MkDocs and its plugin mkdocstrings to document our scripts and generate the documentation website you are reading.

Structure and Syntax example

The documentation is fully stored in our doc folder. Most files are written in Markdown (.md), which is very popular and easy to use.

You could differentiate between two elements:

  1. Non-automated doc elements. They simply make the text appealing. Example in installation.md in our doc folder. To write these requires some knowledge on writing the text which is quite easy to learn having this cheat sheet in close reach.
  2. Automated doc elements using mkdocstrings. What they do is basically to link the code script with the doc texts, for instance, compare the python script add_electricity.py with the api-reference/index.md documentation. To write these kind of automation, get inspiration from our api-reference documentation. Further, to help understanding how things work the official mkdocstrings documentation might help too.

We found three important files/file groups for the documentation:

  1. mkdocs.yml. This is the configuration file for MkDocs and defines the navigation structure.
  2. The .py script with the actual code documentation (docstrings).

The images for documentation should be placed into documentation repository to the folder "doc/img". The content of the folder "documentation/doc/img/" is copied into "pypsa-earth/doc/img/" during building PyPSA-Earth documentation.

Please, if you have problems with the documentation create an issue and let us know.

How to build it locally

To create the documentation locally, you need mkdocs. It can be installed using specifications from doc/requirements.txt. First, we recommend creating a fresh conda environment and activate it:

.../pypsa-earth % conda create --name pypsa-earth-docs python

.../pypsa-earth % conda activate pypsa-earth-docs

Next, install the packages specified in doc/requirements.txt using pip:

.../pypsa-earth % pip install -r doc/requirements.txt

Once installation is completed, the following commands allow you to create the documentation locally:

.../pypsa-earth (pypsa-earth-docs) % cd doc

.../pypsa-earth/doc (pypsa-earth-docs) % mkdocs serve

This will start a local server, usually at http://127.0.0.1:8000/. VScode provides a so called Liveserver extension such that the html file can be opened locally on your computer.

Windows users might face some challenges when building the documentation locally using make. A workaround can be found, but might be time consuming. For instance:

  1. If using Windows PowerShell, you can also run mkdocs serve.

The documentation is built automatically by the CI for every pull request. The documentation is hosted on ReadTheDocs. For more information on our documentation infrastructure and syntax tips, see this page.

No-Code

Instead of contributing code there are alternatives to support the PyPSA-Earth goals. You can fund projects, supervise people, support us with outreach activities or events. Check out our website for more details.

Join us and get involved

Any person/group is welcome to join us. Be it research leader, researcher, undergraduate, or industry professional. You can provide reference data, share suggestions and insights, help fellow modellers asking for assistance in Discord Support channel, contribute into outreach activities and events, and fund projects. A simple way to explore opportunities for collaboration is to join our meetings. All of them are OPEN.