brain-dev
← terug naar het overzicht

Onderzoekssoftware publiceren via Zenodo en de RSD

knowledge · 12 min · onderzoekssoftware zenodo doi

In deze handleiding leer je hoe je eigen onderzoekssoftware citeerbaar maakt, duurzaam archiveert en presenteert aan de buitenwereld. Ik schrijf hem voor onderzoekers en ontwikkelaars bij HAS green academy die zelf software bouwen; je hebt geen technische voorkennis nodig, wel een GitHub-account en schrijfrechten.

Binnen praktijkgericht onderzoek blijft ontwikkelde software vaak steken in een afgeschermde of ongedocumenteerde repository. Daardoor gaan methoden verloren na afloop van een project en krijgen de makers zelden formele erkenning voor hun programmeerwerk. Door software gestructureerd te publiceren volgens de FAIR-principes voor onderzoekssoftware (Barker et al., 2022: Findable, Accessible, Interoperable, Reusable, of kortweg FAIR4RS), maak je van een verzameling codebestanden een volwaardige wetenschappelijke output.

Hierbij spelen twee instrumenten een centrale rol:

1. Wat is verplicht, en welke accounts heb je nodig

Wat is verplicht en wat niet? Het minimum om een DOI en een pagina in de Directory te krijgen:

Verplicht — GitHub. Gebruik je reguliere GitHub-account. Staat de repository onder een organisatie zoals HASUniversity, controleer dan of je daar lid van bent (of vraag om schrijfrechten).

Verplicht — Zenodo. Ga naar zenodo.org en kies Sign up of Log in, met de knop Log in with GitHub. Daarmee koppel je je GitHub-account in één stap aan Zenodo; een ORCID is hier niet voor nodig.

Optioneel (aanbevolen) — ORCID. Een ORCID geeft je software een ondubbelzinnige auteurskoppeling. Vraag er een aan op orcid.org en zet je profiel op 'Everyone' (openbaar), zodat platformen de metadata kunnen uitlezen. Neem het ID exact over zoals ORCID het toont: 16 tekens, waarbij het laatste teken een controleteken is dat ook een hoofdletter X kan zijn. Je hoeft je ORCID niet aan GitHub te koppelen; je vult hem later in bij Zenodo (per upload) en in de Directory.

Nodig voor de Directory — SURFconext. Inloggen gaat met je instellingsaccount via SURFconext. HAS green academy is aangesloten op SURFconext (HBO), maar je instelling moet de Directory ook daadwerkelijk hebben aangezet in het SURFconext-dashboard. Is dat (nog) niet zo, dan kun je bij de beheerders een account op basis van je ORCID aanvragen.

Optioneel — LinkedIn. Alleen handig voor je auteurskaart in de Directory; houd de volledige URL naar je profiel bij de hand.

Officiële achtergrondinformatie:

2. De repository klaarzetten

Stap 1 (verplicht) — maak de repository publiek. Zenodo archiveert alleen publieke repository's. Op GitHub: Settings → onderaan Danger Zone → Change visibility → Make public.

Stap 2 (aanbevolen, niet nodig voor Zenodo) — licentie. Zonder licentie rust er auteursrecht op de code en mag niemand je software juridisch gebruiken of hergebruiken. Kies er een via choosealicense.com (MIT en Apache-2.0 komen het meest voor) en zet het bestand LICENSE in de root. Vul ook de copyrighthouder in (je eigen naam of HAS green academy); GitHub zet daar standaard het woord "Contributors". De volledige lijst met licentiecodes staat in de SPDX-licentielijst.

Stap 3 (optioneel) — CITATION.cff. Dit mag je overslaan: Zenodo werkt ook zonder. Het bestand doet twee dingen: GitHub toont een "Cite this repository"-knop met een kant-en-klare citatie, en Zenodo neemt de makers (inclusief ORCID), de titel en de keywords eruit over in plaats van je GitHub-login en een automatisch gegenereerde titel. Wil je het toevoegen, zet het dan in de repository vóór je de release maakt — Zenodo leest het op het moment dat de release verschijnt.

Let op twee dingen: laat geen verzonnen ORCID staan — met een nummer als 0000-0000-0000-0000 is het bestand ongeldig en negeert Zenodo het volledig. En voeg je het bestand pas ná de release toe, dan staat die release al in Zenodo met je GitHub-login als maker; dat is te repareren zonder nieuwe versie, want de metadata van een gepubliceerde Zenodo-record mag je bewerken. Hulp bij het opstellen en valideren vind je in de Citation File Format documentatie.

3. GitHub aan Zenodo koppelen

Dit is de stap die de automatisering aanzet: daarna maakt elke release automatisch een gearchiveerde Zenodo-versie met DOI.

  1. Zorg dat je repository publiek is (stap 1 van sectie 2).
  2. Ga naar zenodo.org en log in met Log in with GitHub. Je GitHub-account is nu gekoppeld.
  3. Klik rechtsboven op je profielmenu en kies GitHub. Je krijgt de lijst met repository's van je account.
  4. Klik op Sync now als je repository er nog niet bij staat; Zenodo haalt de lijst dan opnieuw op.
  5. Zoek je repository in de lijst en zet de schakelaar erachter op ON.
  6. Ververs de pagina. De repository staat nu als gekoppeld in de lijst.
  7. Lukt het aanzetten niet bij een organisatie-repository, controleer dan op GitHub: Settings → Applications → Authorized OAuth Apps of de organisatie-instellingen (GitHub documentatie over OAuth-toegang). Alleen als de organisatie externe OAuth-apps heeft beperkt, moet een organisatie-eigenaar de Zenodo-app goedkeuren.

Vanaf nu is er geen verdere configuratie nodig: Zenodo luistert naar nieuwe releases van deze repository. De Zenodo-documentatie over het aanzetten van een repository loopt dezelfde stappen langs.

4. Een release maken (en de DOI ophalen)

De DOI ontstaat niet bij het koppelen, maar bij het publiceren van een release.

  1. Open je repository op GitHub.
  2. Klik in de rechterkolom op Releases en daarna op Create a new release (soms weergegeven als Draft a new release). De GitHub-documentatie over releases beschrijft deze stappen per scherm.
  3. Klik bij Choose a tag en typ een versienummer, bijvoorbeeld v1.0.0. Kies Create new tag: v1.0.0 on publish.
  4. Vul een titel in, bijvoorbeeld v1.0.0 — eerste publieke release. Laat je dit leeg, dan gebruikt GitHub de tagnaam.
  5. De beschrijving is optioneel; noteer er bijvoorbeeld in wat er in deze versie zit.
  6. Klik op Publish release. Gebruik je Save draft, dan blijft de release concept, gaat er geen seintje naar Zenodo en komt er dus geen DOI.
  7. Wacht ongeveer een halve minuut. Ga naar Zenodo → profielmenu → Uploads (of je repository in de Zenodo-lijst): daar staat nu de record met een DOI-badge.
  8. Noteer twee identifiers uit die record: de versie-DOI (hoort bij deze release) en de Concept DOI onder "Cite all versions" (hoort bij de software als geheel).
  9. Optioneel: open de record en vul aan wat je wilt (ORCID bij de makers, keywords, een Zenodo-community). Dat mag zonder nieuwe versie.
  10. Bij een volgende update: werk de code bij, maak een nieuwe release (bijvoorbeeld v1.1.0), en Zenodo maakt automatisch een nieuwe versie met een nieuwe versie-DOI. De Concept DOI blijft gelijk en wijst naar de nieuwste versie.

Versie-DOI of Concept DOI: in een paper citeer je de DOI van de specifieke versie, zodat de lezer precies weet welke code is gebruikt. De Concept DOI gebruik je op de softwarepagina en in de badge, want die blijft naar de nieuwste versie wijzen. Zenodo neemt het archief daarnaast ook op in Software Heritage, een archief dat de broncode zelf bewaart. De Zenodo-documentatie over het archiveren van een release laat zien waar je die status terugziet.

5. Een pagina maken in de Research Software Directory

In de Research Software Directory staat je software in context: gekoppeld aan jou als maker, aan de instelling en aan de publicaties die erbij horen. Deze sectie loopt de pagina stap voor stap langs.

  1. Ga naar research-software-directory.org en klik op Sign in (via SURFconext).
  2. Klik op de + naast je avatar en kies New Software.
  3. Vul een naam in (verplicht) en een korte omschrijving in het Engels (aanbevolen) en klik op Save. De pagina bestaat nu, maar is nog niet openbaar.
  4. Ga naar het tabblad Information en plak bij Software DOI de Concept DOI van Zenodo. Klik op Validate: de Directory accepteert alleen een Concept DOI en vervangt een versie-DOI automatisch door de juiste. Na een geldige DOI kun je met één knop de keywords, licentie en contributors uit de DOI-metadata importeren.
  5. Vul bij Source code de URL van je repository in. Dit is de entry die de activiteitsgrafiek en de programmeertalen op de pagina bepaalt.
  6. Voeg bij Contributors jezelf toe (zoek op je naam of ORCID) met je rol en affiliatie. Dit is de stap die de software aan jouw profiel koppelt; zonder contributors is de software van niemand.
  7. Voeg bij Participating organisations de organisatie HAS green academy toe.
  8. Zet bij Publish de pagina op openbaar. Wil je eerst kijken, gebruik dan de preview.
  9. Zet in je persoonlijke instellingen je publieke profiel aan, anders zie je je eigen bijdragen niet terug.
Optioneel: wat je later nog kunt invullen (je hoeft dit niet te doen om te publiceren)

Description (de tekst op de pagina, los van de korte omschrijving), Logo (SVG, max 2 MB), Get started-URL, Licenses, Keywords, Badges, Contact person (één contributor met e-mailknop), Mentions (Reference papers en Related output; citaties oogst het platform via OpenAlex), Testimonials, Package managers (alleen bij PyPI/conda), Software Heritage (SWHID-badge), Communities, Related software, Related projects, Maintainers. Categories ken je niet zelf toe: dat doen de beheerders van de Directory.

Twee dingen om te weten: zolang je je schrijfrechten houdt, kun je je pagina niet verwijderen (neem daarvoor contact op met de beheerders), en voor het uitproberen is er een demoversie die het platform periodiek leegmaakt. De documentatie over het toevoegen van software beschrijft elk veld van deze pagina.

6. Optioneel: badges in de README

Dit is een uiterlijk detail, geen vereiste. Wil je op GitHub meteen laten zien dat de repository een DOI en een pagina in de Directory heeft, zet dan de twee badges bovenaan je README.md: de DOI-badge van Zenodo en de RSD-badge van shields.io, met je eigen DOI en je eigen slug erin.

Wat je daarna bijhoudt

Werk je de code bij, maak dan een nieuwe release. Zenodo maakt automatisch een nieuwe versie en de Directory haalt de nieuwe release en citaties vanzelf op. Gebruik je een CITATION.cff, hoog dan ook het versienummer daarin op.

7. Als het niet meteen lukt

8. Controlelijst

Loop deze lijst na voordat je de publicatie afrondt:

9. Begrippen en beheer

DOI
een blijvende verwijzing naar precies deze versie van je software, ook als het webadres verandert. DataCite registreert hem.
Concept DOI
de verwijzing naar alle versies samen; hij wijst naar de nieuwste release. Gebruik deze op de softwarepagina en in de badge.
Versie-DOI
de verwijzing naar één release. Gebruik deze als je in een paper naar de gebruikte versie verwijst.
ORCID
je persoonlijke onderzoekers-ID (16 tekens, het laatste kan een X zijn). orcid.org
Release en tag
de publicatie van een vastgelegde versie op GitHub, met een label als v1.0.0.
SWHID
de identificatiecode van het archief in Software Heritage; de uitleg staat in de Software Heritage-documentatie.
SPDX
de standaardlijst met licentienamen waaruit de Directory je licentie laat kiezen. spdx.org/licenses

Werk deze handleiding bij na elke grote wijziging in Zenodo, GitHub of de Research Software Directory, en loop hem minimaal één keer per jaar na.

10. Bronnen

Het zijn de bronnen van deze handleiding: de documentatie van de aanbieders zelf, plus het artikel achter de FAIR-principes. Loop je ergens vast, dan is dit de plek om verder te lezen.

↑ terug naar de inhoud