diff --git a/docs/productive/cite/index.rst b/docs/productive/cite/index.rst index c0c6c428..c2e13126 100644 --- a/docs/productive/cite/index.rst +++ b/docs/productive/cite/index.rst @@ -29,5 +29,5 @@ definiert werden. :maxdepth: 0 data - software + software/index journals diff --git a/docs/productive/cite/software.rst b/docs/productive/cite/software.rst deleted file mode 100644 index 1792f7c7..00000000 --- a/docs/productive/cite/software.rst +++ /dev/null @@ -1,363 +0,0 @@ -.. SPDX-FileCopyrightText: 2021 Veit Schiele -.. -.. SPDX-License-Identifier: BSD-3-Clause - -Software zitieren -================= - -James Howison und Julia Bullard führten in ihrem 2016 veröffentlichten Artikel -`Software in the scientific literature `_ -folgende Beispiele in absteigender Reputation auf: - -#. zitieren von Veröffentlichungen, die die jeweilige Software beschreiben -#. zitieren von Bedienungsanleitungen -#. zitieren der Software-Projekt-Website -#. Link auf eine Software-Projekt-Website -#. erwähnen des Software-Namens - -Die Situation bleibt für die Autor*innen von Software dennoch unbefriedigend, -zumal wenn sie sich von den Autor*innen der Software-Beschreibung unterscheiden. -Umgekehrt ist Forschungssoftware leider auch nicht immer gut geeignet um zitiert -zu werden. So werden andere eure Software kaum direkt zitieren können, wenn ihr -ihnen die Software als Anhang von E-Mails schickt. Auch ein Download-Link ist -hier noch nicht wirklich zielführend. Besser stellt ihr einen `Persistent -Identifier (PID) `_ bereit, -um die langfristige Verfügbarkeit eurer Software sicherzustellen. Sowohl `Zenodo -`__- als auch das `figshare -`_-Repository akzeptieren Quellcode einschließlich -Binärdateien und stellen `Digital Object Identifier (DOI) -`_ hierfür bereit. -Gleiches gilt für `CiteAs `_, mit dem sich -Zitierinformationen für Software abrufen lassen. - -.. seealso:: - * `Should I cite? `_ - * `How to cite software “correctly” - `_ - * Daniel S. Katz: `Compact identifiers for software: The last missing link in - user-oriented software citation? - `_ - * `Neil Chue Hong: How to cite software: current best practice - `_ - * `Recognizing the value of software: a software citation guide - `_ - * Stephan Druskat, Radovan Bast, Neil Chue Hong, Alexander Konovalov, Andrew - Rowley, Raniere Silva: `A standard format for CITATION files - `_ - * `Module-5-Open-Research-Software-and-Open-Source - `_ - * Software Heritage: `Save and reference research software - `_ - * `Mining software metadata for 80 M projects and even more - `_ - * `Extensions to schema.org to support structured, semantic, and executable - documents `_ - * `Guide to Citation File Format schema - `_ - * `schema.json - `_ - -.. _zenodo: - -Erstellen eines DOI mit Zenodo ------------------------------- - -`Zenodo `__ ermöglicht die Archivierung von Software und -die Bereitstellung eines DOI für diese Software. Im Folgenden werde ich am -Beispiel des Jupyter-Tutorials zeigen, welche Schritte hierzu erforderlich sind: - -#. Wenn ihr noch keinen `Account für Zenodo `_ - habt, erstellt einen, bevorzugt mit GitHub. - -#. Aktiviert in :menuselection:`Upload --> New Upload` unter :guilabel:`Basic - information` den Button :guilabel:`Reserve DOI` um einen :abbr:`DOI (Digital - Object Identifier)` für euren Upload zu reservieren. Lasst das Formular offen - um später eure Software hochladen zu können. - -#. Erstellt oder ändert die :ref:`codemeta`- und :ref:`cff`-Dateien in eurem - Software-Verzeichnis. - -#. Bindet den Badge in der :file:`README`-Datei eurer Software ein: - - Markdown: - .. code-block:: md - - [![DOI](https://zenodo.org/badge/307380211.svg)](https://zenodo.org/badge/latestdoi/307380211) - - reStructedText: - .. code-block:: rst - - .. image:: https://zenodo.org/badge/307380211.svg - :target: https://zenodo.org/badge/latestdoi/307380211 - -#. Nun wählt das Repository aus, das ihr archivieren wollt: - - .. figure:: zenodo-github.png - :alt: Repositories für Zenodo aktivieren - -#. Überprüft, ob Zenodo einen Webhook in eurem Repository für das - *Releases*-Event erstellt hat: - - .. figure:: zenodo-webhook.png - :alt: Zenodo Webhook - -#. Erstellt ein neues Release: - - .. figure:: github-release.png - :alt: Github Release - -#. Überprüft, ob der DOI korrekt erstellt wurde: - - .. figure:: zenodo-release.png - :alt: Zenodo Release - -Metadaten-Formate ------------------ - -Die `FORCE11 `_ --Arbeitsgruppe hat ein Paper veröffentlicht, in denen Prinzipien des -wissenschaftlichen Software-zitierens dargelegt werden: Arfon Smith, Daniel -Katz, Kyle Niemeyer: `FORCE11 Software Citation Working Group -`_, 2016. Dabei kristallisieren sich -aktuell zwei Projekte für strukturierte Metadaten heraus: - -.. _codemeta: - -CodeMeta -~~~~~~~~ - -`CodeMeta `__ ist ein Austauschschema für -allgemeine Software-Metadaten und Referenzimplementierung für JSON for Linking -Data (`JSON-LD `_). - -Dabei wird eine ``codemeta.json``-Datei im Stammverzeichnis des -Software-Repository erwartet. Die Datei kann :abbr:`z.B. (zum Beispiel)` so -aussehen: - -.. code-block:: javascript - - { - "@context": "https://doi.org/10.5063/schema/codemeta-2.0", - "@type": "SoftwareSourceCode", - "author": [{ - "@type": "Person", - "givenName": "Stephan", - "familyName": "Druskat", - "@id": "http://orcid.org/0000-0003-4925-7248" - }], - "name": "My Research Tool", - "softwareVersion": "2.0", - "identifier": "https://doi.org/10.5281/zenodo.1234", - "datePublished": "2017-12-18", - "codeRepository": "https://github.com/research-software/my-research-tool" - } - -.. seealso:: - * `CodeMeta generator `_ - * `Codemeta Terms `_ - * `GitHub Repository - `_ - -.. _cff: - -Citation File Format -~~~~~~~~~~~~~~~~~~~~ - -`Citation File Format `_ ist ein Schema -für Software-Citation-Metadaten in maschinenlesbarem -:doc:`/data-processing/serialisation-formats/yaml/index`-Format. Dabei sollte -eine Datei ``CITATION.cff`` im Stammverzeichnis des Software-Repository -abgelegt werden. Der Inhalt der Datei kann :abbr:`z.B. (zum Beispiel)` so -aussehen: - -.. code-block:: yaml - - cff-version: "1.1.0" - message: "If you use this tutorial, please cite it as below." - authors: - - - family-names: Schiele - given-names: Veit - orcid: "https://orcid.org/https://orcid.org/0000-0002-2448-8958" - identifiers: - - - type: doi - value: "10.5281/zenodo.4147287" - keywords: - - "data-science" - - jupyter - - "jupyter-notebooks" - - "jupyter-kernels" - - ipython - - pandas - - spack - - pipenv - - ipywidgets - - "ipython-widget" - - dvc - title: "Jupyter tutorial" - version: "0.8.0" - date-released: 2020-10-08 - license: "BSD-3-Clause" - repository-code: "https://github.com/veit/jupyter-tutorial" - -Ihr könnt einfach das obige Beispiel anpassen um eure eigene -``CITATION.cff``-Datei zu erzeugen oder die Website `cffinit -`_ -verwenden. - -Mit `cff-validator `_ -steht euch eine GitHub-Action zur Verfügung, die ``CITATION.cff``-Dateien mit -dem R-Paket ``V8`` überprüft. - -Es gibt auch einige Tools zum Workflow von :ref:`CITATION.cff `-Dateien: - -* `cff-converter-python - `_ konvertiert - ``CITATION.cff``-Dateien in BibTeX, RIS, :ref:`codemeta`- und andere - Dateiformate -* `doi2cff `_ erstellt eine - ``CITATION.cff``-Datei aus einem Zenodo DOI - -Auch GitHub bietet einen Service um die Informationen aus der -``CITATION.cff``-Datei eures GitHub-Repository im APA- und BibTex-Format zu -kopieren. - -.. figure:: github-cite.png - :alt: Popup auf der Zielseite eines GitHub-Repositorys mit der Möglichkeit, - ADA- und BibTex-Formate zu exportieren. - -.. seealso:: - * `GitHub Docs: About CITATION files - `_ - -Wenn ihr einen DOI mit Zenodo registriert, wird die ``CITATION.cff``-Datei aus -dem GitHub-Repository ebenfalls verwendet. Auch `Zotero -`_ interpretiert die :ref:`cff`-Datei in -GitHub-Repositories; Zotero kann jedoch auch ohne :ref:`cff`-Datei -Metainformationen des Repository, wie Unternehmen, Programmiersprache -:abbr:`etc. (et cetera)`, übernehmen. - -Git2PROV --------- - -`Git2PROV `_ generiert PROV-Daten -aus den Informationen eines Git-Repository. - -Auf der Kommandozeile kann die Konvertierung einfach ausgeführt werden mit: - -.. code-block:: console - - $ git2prov git_url [serialization] - -Zum Beispiel: - -.. code-block:: console - - $ git2prov git@github.com:veit/python4datascience.git PROV-JSON - -Insgesamt stehen die folgenden Serialisierungsformate zur Verfügung: - -* ``PROV-N`` -* ``PROV-JSON`` -* ``PROV-O`` -* ``PROV-XML`` - -Alternativ stellt Git2PROV auch einen Web-Server bereit mit: - -.. code-block:: console - - $ git2prov-server [port] - -.. seealso:: - * `Git2PROV: Exposing Version Control System Content as W3C PROV - `_ - * `GitHub-Repository `_ - -HERMES ------- - -`HERMES `_ vereinfacht die Publikation -von Forschungssoftware, indem kontinuierlich in :ref:`cff`, :ref:`codemeta` und -:doc:`Git <../git/index>` vorhandene Metadaten abegrufen werden. Anschließend -werden die Metadaten auch für `InvenioRDM -`_ und `Dataverse -`_ passend zusammengestellt. Schließlich werden auch -:ref:`CITATION.cff ` und :ref:`codemeta.json ` für die -Publikationsrepositories aktualisiert. - -#. ``.hermes/`` in der :ref:`.gitignore `-Datei hinzufügen -#. :ref:`CITATION.cff `-Datei mit zusätzlichen Metadaten bereitstellen - - .. important:: - Stellt sicher, dass ``license`` in der Datei :ref:`CITATION.cff ` - definiert ist; andernfalls wird eure Veröffentlichung von der :ref:`Zenodo - `-Sandbox nicht als Open Access akzeptiert. - -#. HERMES-Workflow konfigurieren - - Der HERMES-Workflow wird konfiguriert in der - :doc:`/data-processing/serialisation-formats/toml/index`-Datei - :file:`hermes.toml`, wobei jeder Schritt einen eigenen Abschnitt erhält. - - Wenn ihr HERMES so konfigurieren wollt, dass die Metadaten aus :doc:`Git - <../git/index>` und :ref:`CITATION.cff ` verwendet werden und die Ablage - in der Zenodo Sandbox, die auf InvenioRDM aufbaut, erfolgen soll, sieht die - :file:`hermes.toml`-Datei folgendermaßen aus: - - .. literalinclude:: hermes.toml - :caption: hermes.toml - :name: hermes.toml - -#. Zugangstoken für Zenodo Sandbox - - Damit GitHub Actions euer Repository in der Zenodo Sandbox veröffentlichen - kann, benötigt ihr ein persönliches Zugangstoken. Hierfür müsst ihr euch bei - der `Zenodo Sandbox `_ anmelden, um dann in - eurem Benutzerprofil einen `persönliches Zugangstoken - `_ mit - dem Namen :samp:`HERMES workflow` und den Geltungsbereichen - :guilabel:`deposit:actions` und :guilabel:`deposit:write` zu erstellen: - - .. image:: zenodo-personal-access-token.png - :alt: Zenodo: Neues persönliches Zugangstoken - -#. Kopiert das neu erstellte Token in ein neues `GitHub Secret - `_ - namens :samp:`ZENODO_SANDBOX` in Ihrem Repository: :menuselection:`Settings - --> Secrets and Variables --> Actions --> New repository secret`: - - .. image:: github-new-action-secret.png - :alt: GitHub: Neues Action-Secret - -#. Konfiguriert die GitHub-Aktion - - Das HERMES-Projekt stellt Vorlagen zur kontinuierlichen Integration in einem - speziellen Repository bereit: `hermes-hmc/ci-templates - `_. Kopiert die Vorlagendatei - `TEMPLATE_hermes_github_to_zenodo.yml - `_ - in das Verzeichnis :file:`.github/workflows/` eures Repository und benennt - sie um, :abbr:`z.B. (zum Beispiel)` in :file:`hermes_github_to_zenodo.yml`. - - Anschließend solltet ihr die Datei durchgehen und nach Kommentaren, die mit - :samp:`# ADAPT` gekennzeichnet sind, suchen. Passt die Datei an eure - Bedürfnisse an. - - Schließlich fügt ihr die Workflow-Datei zur Versionskontrolle hinzu und - schiebt sie auf den GitHub-Server: - - .. code-block:: console - - $ git add .github/workflows/hermes_github_to_zenodo.yml - $ git commit -m ":construction_worker: GitHub action for automatic publication with HERMES" - $ git push - -#. GitHub-Actions sollen Pull Requests in eurem Repository erstellen dürfen - - Der HERMES-Workflow wird keine Metadaten ohne eure Zustimmung - veröffentlichen. Stattdessen erstellt er einen Pull-Request, damit ihr die - hinterlegten Metadaten genehmigen oder ändern könnt. Um dies zu aktivieren, - geht in eurem Repository zu :menuselection:`Settings --> Actions --> General` - und aktiviert im Abschnitt :guilabel:`Workflow permissions` :guilabel:`Allow - GitHub Actions to create and approve pull requests`. diff --git a/docs/productive/cite/software/cff.rst b/docs/productive/cite/software/cff.rst new file mode 100644 index 00000000..d9e05da9 --- /dev/null +++ b/docs/productive/cite/software/cff.rst @@ -0,0 +1,81 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +Citation File Format +==================== + +`Citation File Format `_ ist ein Schema +für Software-Citation-Metadaten in maschinenlesbarem +:doc:`/data-processing/serialisation-formats/yaml/index`-Format. Dabei sollte +eine Datei ``CITATION.cff`` im Stammverzeichnis des Software-Repository +abgelegt werden. Der Inhalt der Datei kann :abbr:`z.B. (zum Beispiel)` so +aussehen: + +.. code-block:: yaml + + cff-version: "1.1.0" + message: "If you use this tutorial, please cite it as below." + authors: + - + family-names: Schiele + given-names: Veit + orcid: "https://orcid.org/https://orcid.org/0000-0002-2448-8958" + identifiers: + - + type: doi + value: "10.5281/zenodo.4147287" + keywords: + - "data-science" + - jupyter + - "jupyter-notebooks" + - "jupyter-kernels" + - ipython + - pandas + - spack + - pipenv + - ipywidgets + - "ipython-widget" + - dvc + title: "Jupyter tutorial" + version: "0.8.0" + date-released: 2020-10-08 + license: "BSD-3-Clause" + repository-code: "https://github.com/veit/jupyter-tutorial" + +Ihr könnt einfach das obige Beispiel anpassen um eure eigene +``CITATION.cff``-Datei zu erzeugen oder die Website `cffinit +`_ +verwenden. + +Mit `cff-validator `_ +steht euch eine GitHub-Action zur Verfügung, die ``CITATION.cff``-Dateien mit +dem R-Paket ``V8`` überprüft. + +Es gibt auch einige Tools zum Workflow von :doc:`CITATION.cff `-Dateien: + +* `cff-converter-python + `_ konvertiert + ``CITATION.cff``-Dateien in BibTeX, RIS, :doc:`codemeta`- und andere + Dateiformate +* `doi2cff `_ erstellt eine + ``CITATION.cff``-Datei aus einem Zenodo DOI + +Auch GitHub bietet einen Service um die Informationen aus der +``CITATION.cff``-Datei eures GitHub-Repository im APA- und BibTex-Format zu +kopieren. + +.. figure:: github-cite.png + :alt: Popup auf der Zielseite eines GitHub-Repositorys mit der Möglichkeit, + ADA- und BibTex-Formate zu exportieren. + +.. seealso:: + * `GitHub Docs: About CITATION files + `_ + +Wenn ihr einen DOI mit Zenodo registriert, wird die ``CITATION.cff``-Datei aus +dem GitHub-Repository ebenfalls verwendet. Auch `Zotero +`_ interpretiert die :doc:`cff`-Datei in +GitHub-Repositories; Zotero kann jedoch auch ohne :doc:`cff`-Datei +Metainformationen des Repository, wie Unternehmen, Programmiersprache +:abbr:`etc. (et cetera)`, übernehmen. diff --git a/docs/productive/cite/software/codemeta.rst b/docs/productive/cite/software/codemeta.rst new file mode 100644 index 00000000..39e3f9fe --- /dev/null +++ b/docs/productive/cite/software/codemeta.rst @@ -0,0 +1,38 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +CodeMeta +======== + +`CodeMeta `__ ist ein Austauschschema für +allgemeine Software-Metadaten und Referenzimplementierung für JSON for Linking +Data (`JSON-LD `_). + +Dabei wird eine ``codemeta.json``-Datei im Stammverzeichnis des +Software-Repository erwartet. Die Datei kann :abbr:`z.B. (zum Beispiel)` so +aussehen: + +.. code-block:: javascript + + { + "@context": "https://doi.org/10.5063/schema/codemeta-2.0", + "@type": "SoftwareSourceCode", + "author": [{ + "@type": "Person", + "givenName": "Stephan", + "familyName": "Druskat", + "@id": "http://orcid.org/0000-0003-4925-7248" + }], + "name": "My Research Tool", + "softwareVersion": "2.0", + "identifier": "https://doi.org/10.5281/zenodo.1234", + "datePublished": "2017-12-18", + "codeRepository": "https://github.com/research-software/my-research-tool" + } + +.. seealso:: + * `CodeMeta generator `_ + * `Codemeta Terms `_ + * `GitHub Repository + `_ diff --git a/docs/productive/cite/software/doi.rst b/docs/productive/cite/software/doi.rst new file mode 100644 index 00000000..103446b8 --- /dev/null +++ b/docs/productive/cite/software/doi.rst @@ -0,0 +1,58 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +Erstellen eines DOI mit Zenodo +============================== + +`Zenodo `__ ermöglicht die Archivierung von Software und +die Bereitstellung eines DOI für diese Software. Im Folgenden werde ich am +Beispiel des Jupyter-Tutorials zeigen, welche Schritte hierzu erforderlich sind: + +#. Wenn ihr noch keinen `Account für Zenodo `_ habt, + erstellt einen, bevorzugt mit GitHub. + +#. Aktiviert in :menuselection:`Upload --> New Upload` unter :guilabel:`Basic + information` den Button :guilabel:`Reserve DOI` um einen :abbr:`DOI (Digital + Object Identifier)` für euren Upload zu reservieren. Lasst das Formular offen + um später eure Software hochladen zu können. + +#. Erstellt oder ändert die :doc:`codemeta`- und :doc:`cff`-Dateien in eurem + Software-Verzeichnis. + +#. Bindet den Badge in der :file:`README`-Datei eurer Software ein: + + Markdown: + + .. code-block:: md + + [![DOI](https://zenodo.org/badge/307380211.svg)](https://zenodo.org/badge/latestdoi/307380211) + + reStructedText: + + .. code-block:: rst + + .. image:: https://zenodo.org/badge/307380211.svg + :target: https://zenodo.org/badge/latestdoi/307380211 + +#. Nun wählt das Repository aus, das ihr archivieren wollt: + + .. figure:: zenodo-github.png + :alt: Enable repositories for Zenodo + +#. Überprüft, ob Zenodo einen Webhook in eurem Repository für das + *Releases*-Event erstellt hat: + + .. figure:: zenodo-webhook.png + :alt: Zenodo webhook + +#. Erstellt ein neues Release: + + .. figure:: github-release.png + :alt: Github releases + +#. Überprüft, ob der :abbr:`DOI (Digital object identifier)` korrekt erstellt + wurde: + + .. figure:: zenodo-release.png + :alt: Zenodo release diff --git a/docs/productive/cite/software/git2prov.rst b/docs/productive/cite/software/git2prov.rst new file mode 100644 index 00000000..9fd5d8a6 --- /dev/null +++ b/docs/productive/cite/software/git2prov.rst @@ -0,0 +1,39 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +Git2PROV +======== + +`Git2PROV `_ generiert PROV-Daten +aus den Informationen eines Git-Repository. + +Auf der Kommandozeile kann die Konvertierung einfach ausgeführt werden mit: + +.. code-block:: console + + $ git2prov git_url [serialization] + +Zum Beispiel: + +.. code-block:: console + + $ git2prov git@github.com:veit/python4datascience.git PROV-JSON + +Insgesamt stehen die folgenden Serialisierungsformate zur Verfügung: + +* ``PROV-N`` +* ``PROV-JSON`` +* ``PROV-O`` +* ``PROV-XML`` + +Alternativ stellt Git2PROV auch einen Web-Server bereit mit: + +.. code-block:: console + + $ git2prov-server [port] + +.. seealso:: + * `Git2PROV: Exposing Version Control System Content as W3C PROV + `_ + * `GitHub-Repository `_ diff --git a/docs/productive/cite/github-cite.png b/docs/productive/cite/software/github-cite.png similarity index 100% rename from docs/productive/cite/github-cite.png rename to docs/productive/cite/software/github-cite.png diff --git a/docs/productive/cite/github-cite.png.license b/docs/productive/cite/software/github-cite.png.license similarity index 100% rename from docs/productive/cite/github-cite.png.license rename to docs/productive/cite/software/github-cite.png.license diff --git a/docs/productive/cite/github-new-action-secret.png b/docs/productive/cite/software/github-new-action-secret.png similarity index 100% rename from docs/productive/cite/github-new-action-secret.png rename to docs/productive/cite/software/github-new-action-secret.png diff --git a/docs/productive/cite/github-new-action-secret.png.license b/docs/productive/cite/software/github-new-action-secret.png.license similarity index 100% rename from docs/productive/cite/github-new-action-secret.png.license rename to docs/productive/cite/software/github-new-action-secret.png.license diff --git a/docs/productive/cite/github-release.png b/docs/productive/cite/software/github-release.png similarity index 100% rename from docs/productive/cite/github-release.png rename to docs/productive/cite/software/github-release.png diff --git a/docs/productive/cite/github-release.png.license b/docs/productive/cite/software/github-release.png.license similarity index 100% rename from docs/productive/cite/github-release.png.license rename to docs/productive/cite/software/github-release.png.license diff --git a/docs/productive/cite/software/hermes.rst b/docs/productive/cite/software/hermes.rst new file mode 100644 index 00000000..f7995a2b --- /dev/null +++ b/docs/productive/cite/software/hermes.rst @@ -0,0 +1,91 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +HERMES +====== + +`HERMES `_ vereinfacht die Publikation +von Forschungssoftware, indem kontinuierlich in :doc:`cff`, :doc:`codemeta` und +:doc:`Git <../../git/index>` vorhandene Metadaten abegrufen werden. Anschließend +werden die Metadaten auch für `InvenioRDM +`_ und `Dataverse +`_ passend zusammengestellt. Schließlich werden auch +:doc:`CITATION.cff ` und :doc:`codemeta.json ` für die +Publikationsrepositories aktualisiert. + +#. ``.hermes/`` in der :ref:`.gitignore `-Datei hinzufügen +#. :doc:`CITATION.cff `-Datei mit zusätzlichen Metadaten bereitstellen + + .. important:: + Stellt sicher, dass ``license`` in der Datei :doc:`CITATION.cff ` + definiert ist; andernfalls wird eure Veröffentlichung von der :doc:`Zenodo + `-Sandbox nicht als Open Access akzeptiert. + +#. HERMES-Workflow konfigurieren + + Der HERMES-Workflow wird konfiguriert in der + :doc:`/data-processing/serialisation-formats/toml/index`-Datei + :file:`hermes.toml`, wobei jeder Schritt einen eigenen Abschnitt erhält. + + Wenn ihr HERMES so konfigurieren wollt, dass die Metadaten aus :doc:`Git + <../../git/index>` und :doc:`CITATION.cff ` verwendet werden und die + Ablage in der Zenodo Sandbox, die auf InvenioRDM aufbaut, erfolgen soll, + sieht die :file:`hermes.toml`-Datei folgendermaßen aus: + + .. literalinclude:: hermes.toml + :caption: hermes.toml + :name: hermes.toml + +#. Zugangstoken für Zenodo Sandbox + + Damit GitHub Actions euer Repository in der Zenodo Sandbox veröffentlichen + kann, benötigt ihr ein persönliches Zugangstoken. Hierfür müsst ihr euch bei + der `Zenodo Sandbox `_ anmelden, um dann in + eurem Benutzerprofil einen `persönliches Zugangstoken + `_ mit + dem Namen :samp:`HERMES workflow` und den Geltungsbereichen + :guilabel:`deposit:actions` und :guilabel:`deposit:write` zu erstellen: + + .. image:: zenodo-personal-access-token.png + :alt: Zenodo: Neues persönliches Zugangstoken + +#. Kopiert das neu erstellte Token in ein neues `GitHub Secret + `_ + namens :samp:`ZENODO_SANDBOX` in Ihrem Repository: :menuselection:`Settings + --> Secrets and Variables --> Actions --> New repository secret`: + + .. image:: github-new-action-secret.png + :alt: GitHub: Neues Action-Secret + +#. Konfiguriert die GitHub-Aktion + + Das HERMES-Projekt stellt Vorlagen zur kontinuierlichen Integration in einem + speziellen Repository bereit: `hermes-hmc/ci-templates + `_. Kopiert die Vorlagendatei + `TEMPLATE_hermes_github_to_zenodo.yml + `_ + in das Verzeichnis :file:`.github/workflows/` eures Repository und benennt + sie um, :abbr:`z.B. (zum Beispiel)` in :file:`hermes_github_to_zenodo.yml`. + + Anschließend solltet ihr die Datei durchgehen und nach Kommentaren, die mit + :samp:`# ADAPT` gekennzeichnet sind, suchen. Passt die Datei an eure + Bedürfnisse an. + + Schließlich fügt ihr die Workflow-Datei zur Versionskontrolle hinzu und + schiebt sie auf den GitHub-Server: + + .. code-block:: console + + $ git add .github/workflows/hermes_github_to_zenodo.yml + $ git commit -m ":construction_worker: GitHub action for automatic publication with HERMES" + $ git push + +#. GitHub-Actions sollen Pull Requests in eurem Repository erstellen dürfen + + Der HERMES-Workflow wird keine Metadaten ohne eure Zustimmung + veröffentlichen. Stattdessen erstellt er einen Pull-Request, damit ihr die + hinterlegten Metadaten genehmigen oder ändern könnt. Um dies zu aktivieren, + geht in eurem Repository zu :menuselection:`Settings --> Actions --> General` + und aktiviert im Abschnitt :guilabel:`Workflow permissions` :guilabel:`Allow + GitHub Actions to create and approve pull requests`. diff --git a/docs/productive/cite/hermes.toml b/docs/productive/cite/software/hermes.toml similarity index 100% rename from docs/productive/cite/hermes.toml rename to docs/productive/cite/software/hermes.toml diff --git a/docs/productive/cite/software/index.rst b/docs/productive/cite/software/index.rst new file mode 100644 index 00000000..cd94b1ef --- /dev/null +++ b/docs/productive/cite/software/index.rst @@ -0,0 +1,109 @@ +.. SPDX-FileCopyrightText: 2021 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +Software zitieren +================= + +James Howison und Julia Bullard führten in ihrem 2016 veröffentlichten Artikel +`Software in the scientific literature `_ +folgende Beispiele in absteigender Reputation auf: + +#. zitieren von Veröffentlichungen, die die jeweilige Software beschreiben +#. zitieren von Bedienungsanleitungen +#. zitieren der Software-Projekt-Website +#. Link auf eine Software-Projekt-Website +#. erwähnen des Software-Namens + +Die Situation bleibt für die Autor*innen von Software dennoch unbefriedigend, +zumal wenn sie sich von den Autor*innen der Software-Beschreibung unterscheiden. +Umgekehrt ist Forschungssoftware leider auch nicht immer gut geeignet um zitiert +zu werden. So werden andere eure Software kaum direkt zitieren können, wenn ihr +ihnen die Software als Anhang von E-Mails schickt. Auch ein Download-Link ist +hier noch nicht wirklich zielführend. Besser stellt ihr einen `Persistent +Identifier (PID) `_ bereit, +um die langfristige Verfügbarkeit eurer Software sicherzustellen. Sowohl `Zenodo +`__- als auch das `figshare +`_-Repository akzeptieren Quellcode einschließlich +Binärdateien und stellen `Digital Object Identifier (DOI) +`_ hierfür bereit. +Gleiches gilt für `CiteAs `_, mit dem sich +Zitierinformationen für Software abrufen lassen. + +.. seealso:: + * `Should I cite? `_ + * `How to cite software “correctly” + `_ + * Daniel S. Katz: `Compact identifiers for software: The last missing link in + user-oriented software citation? + `_ + * `Neil Chue Hong: How to cite software: current best practice + `_ + * `Recognizing the value of software: a software citation guide + `_ + * Stephan Druskat, Radovan Bast, Neil Chue Hong, Alexander Konovalov, Andrew + Rowley, Raniere Silva: `A standard format for CITATION files + `_ + * `Module-5-Open-Research-Software-and-Open-Source + `_ + * Software Heritage: `Save and reference research software + `_ + * `Mining software metadata for 80 M projects and even more + `_ + * `Extensions to schema.org to support structured, semantic, and executable + documents `_ + * `Guide to Citation File Format schema + `_ + * `schema.json + `_ + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 0 + + doi + +Metadaten-Formate +----------------- + +Die `FORCE11 `_ +-Arbeitsgruppe hat ein Paper veröffentlicht, in denen Prinzipien des +wissenschaftlichen Software-zitierens dargelegt werden: Arfon Smith, Daniel +Katz, Kyle Niemeyer: `FORCE11 Software Citation Working Group +`_, 2016. Dabei kristallisieren sich +aktuell zwei Projekte für strukturierte Metadaten heraus: + +:doc:`codemeta` + ist ein Austauschschema für allgemeine Software-Metadaten und + Referenzimplementierung für JSON for Linking Data + (`JSON-LD `_). +:doc:`cff` + ist ein Schema für Software-Citation-Metadaten in maschinenlesbarem + :doc:`/data-processing/serialisation-formats/yaml/index`-Format. + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 0 + + codemeta + cff + +Tools +----- + +:doc:`git2prov` + generiert PROV-Daten aus den Informationen eines Git-Repository. +:doc:`hermes` + vereinfacht die Publikation von Forschungssoftware, indem kontinuierlich + in :doc:`cff`, :doc:`codemeta` und :doc:`Git <../../git/index>` vorhandene + Metadaten abegrufen werden. + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 0 + + git2prov + hermes diff --git a/docs/productive/cite/zenodo-github.png b/docs/productive/cite/software/zenodo-github.png similarity index 100% rename from docs/productive/cite/zenodo-github.png rename to docs/productive/cite/software/zenodo-github.png diff --git a/docs/productive/cite/zenodo-github.png.license b/docs/productive/cite/software/zenodo-github.png.license similarity index 100% rename from docs/productive/cite/zenodo-github.png.license rename to docs/productive/cite/software/zenodo-github.png.license diff --git a/docs/productive/cite/zenodo-personal-access-token.png b/docs/productive/cite/software/zenodo-personal-access-token.png similarity index 100% rename from docs/productive/cite/zenodo-personal-access-token.png rename to docs/productive/cite/software/zenodo-personal-access-token.png diff --git a/docs/productive/cite/zenodo-personal-access-token.png.license b/docs/productive/cite/software/zenodo-personal-access-token.png.license similarity index 100% rename from docs/productive/cite/zenodo-personal-access-token.png.license rename to docs/productive/cite/software/zenodo-personal-access-token.png.license diff --git a/docs/productive/cite/zenodo-release.png b/docs/productive/cite/software/zenodo-release.png similarity index 100% rename from docs/productive/cite/zenodo-release.png rename to docs/productive/cite/software/zenodo-release.png diff --git a/docs/productive/cite/zenodo-release.png.license b/docs/productive/cite/software/zenodo-release.png.license similarity index 100% rename from docs/productive/cite/zenodo-release.png.license rename to docs/productive/cite/software/zenodo-release.png.license diff --git a/docs/productive/cite/zenodo-webhook.png b/docs/productive/cite/software/zenodo-webhook.png similarity index 100% rename from docs/productive/cite/zenodo-webhook.png rename to docs/productive/cite/software/zenodo-webhook.png diff --git a/docs/productive/cite/zenodo-webhook.png.license b/docs/productive/cite/software/zenodo-webhook.png.license similarity index 100% rename from docs/productive/cite/zenodo-webhook.png.license rename to docs/productive/cite/software/zenodo-webhook.png.license