Skip to content

Contribution Guidelines

The authoritative contribution guide is CONTRIBUTING.md in the repository root (GitLab or a local clone). Below is the current text from that file.

CONTRIBUTING.md

Contributing to PVGIS

Thank you for your interest in PVGIS (Photovoltaic Geographic Information System). This repository hosts the Python package, CLI, and documentation for PVGIS version 6 and later. The public Web API is served from a separate deployment; use the right issue template so we can route your report quickly.

Where to get help

Resource Link
Documentation (search, tutorials, CLI, Web API) pvgis.pages.code.europa.eu/pvgis
Issue tracker code.europa.eu/pvgis/pvgis/-/issues
Email JRC-PVGIS@ec.europa.eu

For security issues affecting the public Web API, contact us directly (see README — Contact & Support); do not post exploit details in public issues.

Reporting bugs and requesting features

  1. Search the documentation and existing issues first.
  2. Open a new issue and pick the template that matches your report:
Template Use when
Web_API Problems with the public HTTPS API (wrong status, response, rate limits, OpenAPI docs, etc.)
Python_CLI Problems with the pvgis command-line tool (crashes, wrong output, install, flags)

Templates live in .gitlab/issue_templates/. They ask for reproduction details we need (e.g. request_id / X-Request-ID for API calls, pvgis --version and example commands for CLI).

You can also email an issue to this project.

Contributor Licence Agreement (CLA) and commit sign-off

PVGIS is a European Commission project on code.europa.eu. Read and follow the official contribution and CLA material:

Document Link
How contributions are handled (project managers) dco-cla/README.md
Contributing guidelines (contributors) dco-cla/contributing-guidelines.md
Contributor Licence Agreement (sign and return) dco-cla/ec-cla.pdf
GPG sign-off on commits dco-cla/signing_with_gpg.md
Developer Certificate of Origin (minor contributions / docs) dco-cla/dco.md
Managing signed CLAs in EURECA (project managers) dco-cla/managing_CLA_files.md

Send a signed Contributor Licence Agreement (PDF) for this project to: JRC-PVGIS@ec.europa.eu

Third-party dependencies (NOTICE and third_party/)

When you change dependencies in pyproject.toml, regenerate NOTICE and third_party/ as required in the CLA and contributing guidelines linked above.

Locally (from the repository root, with the same environment you use to run PVGIS):

python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .[all]
.venv/bin/python -m pip install pip-licenses
PYTHONPATH=tools .venv/bin/python -m pvgis_third_party_licenses

Generator: tools/pvgis_third_party_licenses/.

On GitLab CI: a push to DEVELOPMENT_BRANCH that changes pyproject.toml runs the third_party_licenses job. If NOTICE or third_party/ drift from the generator, the job opens a merge request with updated artefacts (requires PVGIS_BOT_TOKEN — see comments in that file). Commit any regenerated files in your MR if you run the tool locally instead.

Contributing code

Get set up

  • Follow Installation (editable install recommended for development).
  • Run tests locally — see Pytest.

Workflow

  1. Open an issue (or pick an existing one) to discuss non-trivial changes when useful.
  2. Branch from the current development line using our naming convention:
<issue-number>-<short-description>

Example: 129-add-different-panel-orientation-tilt. Details: Development conventions — Branch naming.

  1. Commit with clear messages and GPG sign-off (see CLA and commit sign-off above). We follow Conventional Commits; see commit message guidance.

  2. Open a merge request on code.europa.eu/pvgis/pvgis with:

  3. What changed and why
  4. Link to the issue (Closes #… when applicable)
  5. Tests for behaviour changes
  6. Doc updates under docs/ when user-facing behaviour changes

Code layout (new features)

Typical integration path:

  1. Numerics in pvgis/algorithms/
  2. Public API in pvgis/api/
  3. Optional Typer commands in pvgis/cli/

See Adding new features for detail.

Style

  • Docstrings: NumPy style
  • Linting / formatting: match CI (see project tooling in pyproject.toml)
  • Tests: add or extend suites under tests/

Documentation contributions

User-facing docs are built with MkDocs Material from docs/ (config: properdocs.yml). Fix typos, tutorials, CLI pages, or Web API guides via merge request the same way as code. Published site: pvgis.pages.code.europa.eu/pvgis.

License

This project is distributed under the European Union Public Licence v1.2. Contributor rights and obligations are set out in the code.europa.eu DCO/CLA documents linked above.

For implementation detail when adding capabilities, see also Adding new features and Conventions.