Contributing

Contributions to eDisGo are welcome. This page covers how to set up a development environment, the code standards we follow, how to run the tests and how to build the documentation.

Development installation

Clone the repository and install it in editable mode with the development extras into a fresh Python 3.11 virtual environment:

git clone https://github.com/openego/eDisGo.git
cd eDisGo
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pre-commit install   # install the git pre-commit hooks

On Windows, create the environment from eDisGo_env_dev.yml with conda first (see Installation).

Code standards

  • pre-commit hooks — formatting and linting (Ruff, which replaced flake8, isort, pyupgrade and Black) run on every commit; with the hooks installed you cannot push until they pass. Run them on demand with pre-commit (most issues are fixed automatically).

  • Tests — all tests must pass and new code must come with tests.

  • Type hints — add type hints to new functions; they are rendered into the API reference.

  • Docstrings — document parameters and behaviour (NumPy/Google style, parsed by Napoleon). For @property pairs, document both getter and setter in the getter’s docstring.

  • Documentation — update the relevant doc/ pages and add a whatsnew entry for user-visible changes.

Running the tests

Tests use pytest. Some tests are slow, require a local database, or only run on Linux; enable them with the corresponding flags:

python -m pytest tests/ --runslow --runlocal --runonlinux

For faster runs you can parallelise with -n (locally use a small number of workers) and re-run flaky database tests:

python -m pytest tests/ -n 3 --reruns 3 --reruns-delay 5 --runslow --html=report.html

Building the documentation

The documentation is built with Sphinx (the API reference is generated automatically from the source by AutoAPI, and the tutorial notebooks are rendered by nbsphinx, which requires pandoc). From the repository root:

sphinx-build -E -a -b html ./doc/ <outputdir>

To check external links:

sphinx-build ./doc/ -b linkcheck -d _build/doctrees _build/html

Adding -n (nitpicky mode) additionally reports unresolved cross-references and type hints.

Submitting changes

Develop on a feature branch and open a pull request against dev. A PR can be merged once the automated tests pass (in particular the Python 3.11 tests), the branch is up to date with dev, the pre-commit checks are green and a maintainer has reviewed it. Please make sure new dependencies are added to setup.py and rtd_requirements.txt, and new features are documented in whatsnew.