Contributing to RegionMatch

Thank you for your interest in contributing to RegionMatch — we’re very happy you’re here! 🌱

RegionMatch is developed at the Climate Service Center Germany (GERICS), Helmholtz-Zentrum Hereon, and released as open-source software because we believe that transparent, reusable tools are essential for climate services and research.

Whether you want to report a bug, improve the documentation, or contribute code: your input is very welcome.

💬 Getting in touch

The easiest way to start is via the GitLab issue tracker:

👉 https://gitlab.dkrz.de/ch1187/plugins4freva/regionmatch

Please feel free to open an issue if you:

have a question about the plugin
found a bug or unexpected behaviour
miss a feature
want to discuss an idea before implementing it

🧑‍💻 Contributing code

Development workflow

The source code is hosted on GitLab. To contribute:

Create a GitLab account (if you don’t have one yet)
Fork the repository to your own account
Implement your changes in your fork
Open a merge request against the main repository

If you are unsure about anything along the way, don’t hesitate to open an issue and ask — we’re happy to help.

Repository: https://gitlab.dkrz.de/ch1187/plugins4freva/regionmatch

Local setup

Clone your fork:

git clone https://gitlab.dkrz.de/<your-user>/regionmatch.git
cd regionmatch

Create and activate a virtual environment:

python -m venv venv
source activate venv/bin/activate  # or venv/Scripts/Activate.bat on Windows

Install the package in development mode

pip install -e ./regionmatch/[dev]

🛠 Development helpers

Makefile shortcuts

Several common development tasks are bundled in the Makefile located in the repository root. On Linux, you can run:

make help

to get an overview of available commands.

🎨 Code style and quality checks

To keep the codebase readable and maintainable, we rely on automated tools:

Black – code formatting
blackdoc – formatting of docstrings and documentation
Flake8 – general code quality
isort – import ordering
mypy – static type checking
reuse – license compliance
cffconvert – validation of CITATION.cff

These checks are automatically run via pre-commit hooks.

Setting up pre-commit (recommended)

pre-commit install

From now on, formatting and checks will run automatically before each commit.

You can also run them manually:

pre-commit run --all-files

Skipping checks (git commit --no-verify) is possible, but note that the CI pipeline will fail if formatting issues remain.

📄 Licenses and copyright

When adding new files, please ensure that license headers are set correctly. We use reuse to manage and validate licensing information.

A helper script is provided:

python .reuse/add_license.py <shortcut> <file>

Available shortcuts:

code – for Python source files
docs – for documentation files
supp – for other supporting files

If you’re unsure which license applies, feel free to ask the maintainers.

📚 Contributing to the documentation

The documentation is built with Sphinx and hosted on Read the Docs.

To build the docs locally:

cd docs
pip install -r requirements.txt ../[docs]
make html

You can then open the documentation locally at:

docs/_build/html/index.htm

Documentation sources live in the docs/ folder and can be edited directly.

🔄 Updating the plugin template

RegionMatch was originally generated using the Freva plugin template:

https://gitlab.dkrz.de/ch1187/plugins4freva/freva-plugin-template.git

If you need to update the project skeleton, please refer to the template repository for detailed instructions.

Thanks again for your interest in contributing — we really appreciate your help in making RegionMatch better! 🌍