# 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 questions and feedback, * propose and develop new features, * report bugs, * submit bug fixes, * improve documentation, * share your insights on energy modelling needs for different regions, * contribute datasets ## Code PyPSA-Earth is a community effort which exists thanks to coordinated contributions on many volunteers around the world. Every typo fix counts! ### Linting and pre-commit For every code contribution, the [pre-commit](https://pre-commit.com/index.html) utility must be executed. That is a way to keep the code tidy and licensing consistent with minimal effort. We use [Black](https://github.com/psf/black) as code style and aim for [REUSE compliance](https://reuse.software/)). `pre-commit` is part of pypsa-earth environment. To use it, you can chose from two options: * 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/.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](https://www.mkdocs.org/) and its plugin [mkdocstrings](https://mkdocstrings.github.io/) 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](https://www.markdownguide.org/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](https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/scripts/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](https://mkdocstrings.github.io/) 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](https://github.com/pypsa-meets-earth/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: ```bash .../pypsa-earth % conda create --name pypsa-earth-docs python ``` ```bash .../pypsa-earth % conda activate pypsa-earth-docs ``` Next, install the packages specified in `doc/requirements.txt` using `pip`: ```bash .../pypsa-earth % pip install -r doc/requirements.txt ``` Once installation is completed, the following commands allow you to create the documentation locally: ```bash .../pypsa-earth (pypsa-earth-docs) % cd doc ``` ```bash .../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](https://pypsa-earth.readthedocs.io/en/latest/). For more information on our documentation infrastructure and syntax tips, see [this page](https://pypsa-earth.readthedocs.io/en/latest/how_to_docs.html). ## 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](https://pypsa-meets-earth.github.io) 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](https://discord.gg/AnuJBk23FU) 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**. * [List of meetings and times](https://github.com/pypsa-meets-earth/pypsa-earth#get-involved) * **Discord** * Chat with the community, team up on features, exchange with developers, code in voice channels * [Discord invitation link](https://discord.gg/AnuJBk23FU)