Metadata-Version: 2.4
Name: hermes-plugin-rsd
Version: 0.1.0
Summary: A HERMES plugin to harvest and deposit metadata in a Research Software Directory instance.
License: EUPL-1.2
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/CC-BY-4.0.txt
License-File: LICENSES/CC0-1.0.txt
License-File: LICENSES/EUPL-1.2.txt
Author: Christian Meeßen
Author-email: christian.meessen@gfz.de
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: hermes (>=0.9,<1)
Requires-Dist: pydantic (>=2.13.5,<3.0.0)
Requires-Dist: pydantic-core (>=2.48.0,<3.0.0)
Requires-Dist: requests (>=2.34.2,<3.0.0)
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2025, 2026 GFZ Helmholtz Centre for Geosciences
SPDX-FileContributor: Christian Meeßen (GFZ) <christian.meessen@gfz.de>

SPDX-License-Identifier: CC-BY-4.0
-->

# hermes RSD plugin

This repository contains plugins for [hermes](https://hermes.software-metadata.pub/en/latest/) that provide a way to interact with a Research Software Directory (RSD) instance.

The **RSD harvest plugin** harvests metadata from existing RSD entries, whereas the **RSD deposit plugin** can be used to create or update entries in an RSD.

A working example based on the official [hermes showcase](https://github.com/softwarepub/showcase) can be found in [RSD-as-a-service/showcase](https://codebase.helmholtz.cloud/research-software-directory/hermes-showcase-rsd).

The metadata mapping applied in this plugin is documented in [Metadata mapping.md](./Metadata%20mapping.md).

## How to

### Prerequisites

This plugin requires hermes 0.9.x and an RSD instance running a support version. The plugin will check the remote RSD version and display a warning if it differs. You can check the version of an RSD by querying `/api/fe` and checking the `rsd_version` property.

Supported RSD versions: v5.3.1 to v5.4.4.

#### RSD API Token

To be able to push data to an RSD instance an API token is required. Follow the [instructions](https://helmholtz.software/documentation/users/user-settings/#api-access-tokens) of your RSD instance to obtain the token.

### Plugin configuration

Follow the [tutorial](https://hermes.software-metadata.pub/en/latest/tutorials/automated-publication-with-ci.html) on the hermes website to set up your hermes workflow.

The plugins require three variable definitions:

- `rsd_url`, the domain of the RSD where you would like to harvest/deposit
- `software_slug` the slug, i.e. `https://helmholtz.software/software/<slug>` of your software. You need to define this the first time you are using the plugin
- `RSD_API_TOKEN` is an **environment variable** that must be set

Extend your `hermes.toml` as follows

```toml
[harvest]
sources = ["rsd"]

[harvest.rsd]
rsd_url = "https://helmholtz.software"
software_slug = "<your-desired-slug>"

[deposit]
target = "rsd"

[deposit.rsd]
rsd_url = "https://helmholtz.software"
software_slug = "<your-desired-slug>"
```

## Development setup

Requirements

* pyenv
* poetry

```
pyenv install 3.10
pyenv local 3.10
pyenv shell 3.10
poetry env use $(which python)
poetry install
eval $(poetry env activate)
```

Create a `.env` file in the root of the directory and add `RSD_API_TOKEN`.

To run, start the hermes pipeline

```bash
source .env
hermes harvest
hermes process
hermes curate
hermes postprocess
hermes deposit
```

## Using the pre-commit hook to automatically annotate SPDX headers

To use a pre-commit hook that will automatically annotate all commits with file headers, run

```bash
make install-pre-commit-hook
```

Follow the instructions.

**NOTE** the pre-commit hook can not handle partial commits, i.e. only partially committing changes in one file. To do
this, disable pre-commit hooks using the `-n`/`--no-verify` flag:

```bash
git commit -n
```

## Funding

This repository is part of the [Software CaRD](https://helmholtz.software/software/software-card) project and has been funded by [Helmholtz Metadata Collaboration](https://helmholtz-metadaten.de/). 

## License and Copyright

Copyright GFZ Helmholtz Centre for Geosciences.

This software is primarily licensed EUPL-1.2. Some files are licensed Apache-2.0, CC-BY-4.0 or CC0-1.0, as indicated
in their respective headers.

