# 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)**](https://www.climate-service-center.de/), 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: 👉 **** 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: 1. Create a GitLab account (if you don’t have one yet) 2. Fork the repository to your own account 3. Implement your changes in your fork 4. 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: ### Local setup Clone your fork: ```bash git clone https://gitlab.dkrz.de//regionmatch.git cd regionmatch ``` Create and activate a virtual environment: ```bash python -m venv venv source activate venv/bin/activate # or venv/Scripts/Activate.bat on Windows ``` Install the package in development mode ```bash 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: ```bash 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) ```bash pre-commit install ``` From now on, formatting and checks will run automatically before each commit. You can also run them manually: ```bash 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: ```bash python .reuse/add_license.py ``` 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: ```bash cd docs pip install -r requirements.txt ../[docs] make html ``` You can then open the documentation locally at: ```bash 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: 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! 🌍