Merge pull request #295 from softwarepub/feature/287-governance-websi…

…te-structure Describe governance and restructure website and repo scopes
softwarepub · Jan 16, 2025 · 58846b0 · 58846b0
2 parents b119e49 + 363c912
commit 58846b0
Show file tree

Hide file tree

Showing 19 changed files with 414 additions and 26 deletions.
diff --git a/.github/workflows/check-licenses.yml b/.github/workflows/check-licenses.yml
@@ -13,6 +13,6 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: REUSE Compliance Check
-      uses: fsfe/reuse-action@v1
+      uses: fsfe/reuse-action@v5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -139,3 +139,27 @@ a [forking pattern](https://docs.github.com/en/get-started/quickstart/fork-a-rep
 1. Delete the release branch.
 1. 💡 If something goes wrong in the release branch, you can always delete it, fix things in a feature branch, merge
   into `develop` following the workflow above, and start anew.
+
+## Build
+
+To build `hermes` locally, run the
+following command from the project root:
+
+```shell
+poetry install
+```
+
+To build the documentation in your *poetry* environment, run the
+following commands from the project root:
+
+```shell
+poetry install --with docs
+poetry run task docs-build
+```
+
+Or use [`sphinx-autobuild`](https://github.com/executablebooks/sphinx-autobuild) to enable a self-updating preview service:
+
+```shell
+poetry install --with docs
+poetry run task docs-live
+```
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -0,0 +1,81 @@
+<!--
+SPDX-FileCopyrightText: 2024 German Aerospace Center (DLR)
+SPDX-FileContributor: Stephan Druskat
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+## Governance
+
+The HERMES project employs a lightweight governance model.
+
+All decisions are made by the [HERMES Steering Group](#hermes-steering-group) 
+together with the maintainer(s) of the repositories affected by the decision.
+
+Decisions that adhere to a single [repository in the scope of the HERMES project](#hermes-project-repositories)
+are made by *lazy consensus*: 
+
+1. The maintainer of the repository makes a decision and notifies the HERMES Steering Group
+(using `@softwarepub/hermes-steering-group` mention).
+2. If no members of the Steering Group veto the decision within the decision period of one week (168 hours),
+the decision becomes effective and can be acted upon. 
+The maintainer and any member of the Steering Group can ask for a longer decision period, 
+which must be granted. 
+During this period, the steering committee should meet to discuss the decision.
+3. If one or more members of the Steering Group veto the decision, 
+the decision is discussed until consensus is reached.
+
+Decisions that adhere to more than one [repository in the scope of the HERMES project](#hermes-project-repositories)
+must be based on full consensus within the Steering Group. 
+
+
+### HERMES project repositories
+
+The following are the repositories that are governed by the Steering Group. 
+
+- <https://github.com/softwarepub/hermes> (Maintainer: Stephan Druskat)
+- <https://github.com/softwarepub/ci-templates> (Maintainer: Oliver Bertuch)
+- <https://github.com/softwarepub/hermes-plugin-git> (Maintainer: Sophie Kernchen)
+- <https://github.com/softwarepub/hermes-plugin-python> (Maintainer: Michael Meinel)
+- <https://github.com/softwarepub/showcase> (Maintainer: Oliver Bertuch)
+- <https://github.com/softwarepub/schema.software-metadata.pub> (Maintainer: Michael Meinel)
+- <https://github.com/softwarepub/github-action> (Maintainer: Oliver Bertuch)
+- <https://github.com/softwarepub/concept-paper> (Maintainer: Stephan Druskat)
+
+New repositories may be added to, 
+and existing repositories may be removed from, 
+the project by the [Steering Group](#hermes-steering-group)
+by updating the above list.
+Any update needs lazy consensus [as defined above](#governance) from all members of the Steering Group.
+
+### HERMES Steering Group
+
+The HERMES Steering Group has three members, 
+each of whom represents one of the three Helmholtz centers 
+who were funded under the original Helmholtz Metadata Collaboration project (ZT-I-PF-3-006), i.e.,
+German Aerospace Center (DLR), 
+Helmholtz-Zentrum Dresden-Rossendorf (HZDR), 
+Forschungszentrum Jülich (FZJ).
+
+Currently the Steering Group consists of:
+
+- Stephan Druskat (DLR), stephan.druskat@dlr.de
+- David Pape (HZDR), d.pape@hzdr.de
+- Nitai Heeb (FZJ), n.heeb@fz-juelich.de
+
+
+Whenever a member of the Steering Group wants to step down,
+they are asked to nominate a successor.
+If no successor is named,
+the two remaining members seek a successor affiliated with the Helmholtz center of the leaving member.
+New members of the Steering Group join if neither of the other two members disagrees with the decision to join. 
+
+### HERMES repository maintainers
+
+Each [repository in the scope of the HERMES project](#hermes-project-repositories) should have one maintainer at all times.
+The Steering Group appoints the maintainer for this repository in agreement with the appointed person.
+Whenever a maintainer wants to step down,
+they are asked to nominate a successor.
+If no successor is named,
+the Steering Group seeks a successor.
+One member of the Steering Group steps in as interim maintainer until a successor is found.
diff --git a/LICENSE.md b/LICENSE.md
@@ -19,4 +19,4 @@ The work contained in this repository is licensed under different licenses:
 Please see the individual files for more accurate information.
 Please also let us know in a new issue if you find content that seems to be unlicensed.
 
-> We provide copyright and license information according to the [REUSE Specification 3.0](https://reuse.software/spec/).
+> We provide copyright and license information according to the [REUSE Specification 3.3](https://reuse.software/spec-3.3/).
diff --git a/REUSE.toml b/REUSE.toml
@@ -0,0 +1,19 @@
+version = 1
+
+[[annotations]]
+path = ["docs/source/_static/img/*.jpg", "docs/source/_static/img/*.png"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "All rights reserved"
+SPDX-License-Identifier = "CC-BY-ND-4.0"
+
+[[annotations]]
+path = ["docs/source/**/*.md"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "German Aerospace Center (DLR), Helmholtz-Zentrum Dresden-Rossendorf, Forschungszentrum Jülich"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
+[[annotations]]
+path = ["REUSE.toml"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "German Aerospace Center (DLR), Helmholtz-Zentrum Dresden-Rossendorf, Forschungszentrum Jülich"
+SPDX-License-Identifier = "CC0-1.0"
diff --git a/docs/source/_static/img/bertuch.jpg b/docs/source/_static/img/bertuch.jpg
diff --git a/docs/source/_static/img/druskat.jpg b/docs/source/_static/img/druskat.jpg
diff --git a/docs/source/_static/img/juckeland.jpg b/docs/source/_static/img/juckeland.jpg
diff --git a/docs/source/_static/img/kelling.jpg b/docs/source/_static/img/kelling.jpg
diff --git a/docs/source/_static/img/kernchen.jpg b/docs/source/_static/img/kernchen.jpg
diff --git a/docs/source/_static/img/knodel.jpg b/docs/source/_static/img/knodel.jpg
diff --git a/docs/source/_static/img/meinel.png b/docs/source/_static/img/meinel.png
diff --git a/docs/source/_static/img/opengraph.png b/docs/source/_static/img/opengraph.png
diff --git a/docs/source/_static/img/pape.jpg b/docs/source/_static/img/pape.jpg
diff --git a/docs/source/_static/img/schlauch.jpg b/docs/source/_static/img/schlauch.jpg
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -19,16 +19,25 @@ SPDX-FileContributor: David Pape
 This is work in progress.
 ```
 
-Research software must be formally published to satisfy FAIR principles and unlock academic credit. Publication
-repositories enable this and provide PIDs for software versions, but only through tedious, mostly manual process.
-
-The HERMES workflow enables automated publication of rich research software metadata and artifacts to publication
-repositories using open source tooling.
-
-We follow a *push based* model and run in continuous integration (CI) infrastructures integrated in common code platforms
-such as GitHub or GitLab to avoid going out of service and overcome limitations of pull-based web services.
-
-Rich descriptive metadata is the key element to useful software publications. We harvest existing metadata from source
+Research software must be formally published to satisfy the 
+[*FAIR Principles for Research Software*](https://doi.org/10.15497/RDA00068),
+improve software sustainability and 
+enable software citation. 
+Publication repositories make software publication possible 
+and provide PIDs for software versions.
+But software publication is often a tedious, manual process. 
+
+HERMES workflows automate the publication of research software with rich metadata
+using an open source tool, the `hermes` Python package. 
+
+HERMES follows a *push-based* model and runs in 
+continuous integration (CI) systems.
+This way, it helps overcome limitations of platform-centric
+pull-based services and grants its users full control over the
+publication process and the metadata compiled for the publication. 
+
+Rich descriptive metadata is the key element to useful software publications. 
+We harvest existing metadata from source
 code repos and connected platforms, then process, collate and present them for curation, thus preparing software for
 automatic submission to publication repositories.
 
@@ -71,32 +80,34 @@ adr/index
 api/index
 ```
 
+```{toctree}
+:maxdepth: 1
+:caption: HERMES project
+project/index
+project/events
+project/presentations
+```
+
 ```{toctree}
 :hidden:
 :caption: Related
-Project Website <https://project.software-metadata.pub>
 Concept Paper <https://arxiv.org/abs/2201.09015>
 ```
 
-## Feedback
-
-This is an open repository to collect feedback on the HERMES workflow.
+## Get in touch!
 
-We see our project as part of a global and inter-disciplinary effort to improve the state of the art in
-research software engineering, maintenance and scholarly communications around research software. We therefore
-appreciate any feedback you may have on the HERMES project itself and any of its outputs.
+HERMES is part of a global and interdisciplinary effort to improve the state of the art in 
+research software engineering, maintenance and scholarly communications around research software. We
+appreciate any feedback you may have.
 
 **How to give feedback**
 
-Either [create an issue](https://github.com/hermes-hmc/workflow/issues/new/choose) in our project repository or
-[send us an email](mailto:team@software-metadata.pub?subject=HERMES%20WOrkflow%20Reachout).
+Either [create an issue](https://github.com/softwarepub/hermes/issues/new/choose) in the main `hermes` repository or 
+[send us an email](mailto:team@software-metadata.pub?subject=HERMES%20Workflows).
 
 ## Acknowledgements
 
-This project (ZT-I-PF-3-006) was funded by the *Initiative and Networking Fund*
-of the [Helmholtz Association](https://www.helmholtz.de/en/about-us/structure-and-governance/initiating-and-networking)
-in the framework of the [Helmholtz Metadata Collaboration](https://helmholtz-metadaten.de)'s
-[2020 project call](https://helmholtz-metadaten.de/en/projects/hmc-projects-2020).
+HERMES was developed with initial funding from the [Helmholtz Metadata Collaboration](https://helmholtz-metadaten.de) ([Helmholtz INF](https://www.helmholtz.de/en/about-us/structure-and-governance/initiating-and-networking) grantZT-I-PF-3-006).
 
 ```{include} ../../LICENSE.md
 ```

diff --git a/docs/source/project/events.md b/docs/source/project/events.md
@@ -0,0 +1,27 @@
+# Events
+
+(rsecon2022)=
+
+## HERMES MVP Workshop - 2022-09-07
+
+During [RSE Conference 2022](https://rsecon2022.society-rse.org/) we host a
+[workshop to present our "minimum viable product"](https://virtual.oxfordabstracts.com/#/event/3101/submission/98)
+to a broader RSE audience and hack on further improvements.
+
+Would be nice to meet you there!
+
+(kickoff)=
+
+## HERMES Kickoff Workshop - 2021-11-12
+
+In November 2021, the [HERMES project ran a kickoff workshop](https://events.hifis.net/event/205/)
+with partner projects, stakeholders and interested parties. The [event website](https://events.hifis.net/event/205/)
+provides general information about the workshop as well as the slides and
+recordings for the presentations given at the workshop:
+
+1. **Daniel Garijo** (Universidad Politécnica de Madrid): *SOMEF: A Metadata Extraction Framework from Software Documentation*
+2. **Carlos Martinez-Ortiz** (Netherlands eScience Center): *Research Software Directory: past - present - future*
+3. **Ana Trisovic** (Harvard University): *The Dataverse Project - Supporting (research) code in dataset publications*
+4. **Sara Gonzales** (Northwestern University): *Powering open science and collaboration with Invenio*
+5. **Dorothea Iglezakis** (University of Stuttgart): *Handling Research Software: Projects in Stuttgart*
+6. **Felix Bach** (Karlsruhe Institute of Technology): *Code management in openCARP & publication on RADAR4KIT*
diff --git a/docs/source/project/index.md b/docs/source/project/index.md
@@ -0,0 +1,93 @@
+---
+sd_hide_title: true
+---
+
+# Overview
+
+**HERMES** is an acronym for "**HE**lmholtz **R**ich **ME**tadata **S**oftware publication".
+
+The project received initial funding as a 
+[Helmholtz Metadata Collaboration](https://helmholtz-metadaten.de) 
+[2020 cohort project](https://helmholtz-metadaten.de/en/inf-projects/hermes-helmholtz-rich-metadata-software-publication) 
+(ZT-I-PF-3-006) from the *Initiative and Networking Fund*
+of the [Helmholtz Association](https://www.helmholtz.de/en/about-us/structure-and-governance/initiating-and-networking).
+
+The project developed the initial implementation of the
+[HERMES workflow](../index.md)
+and cooperated with the upstream [InvenioRDM](https://invenio-software.org/products/rdm/)
+and [Dataverse](https://dataverse.org) projects. 
+
+## Members
+
+Made by [DLR](https://dlr.de), [HZDR](https://hzdr.de) and [FZJ](https://fz-juelich.de)
+
+<p>
+
+```{image} ../_static/img/schlauch.jpg
+    :alt: Tobias Schlauch
+    :class: member
+    :target: https://www.dlr.de/sc/desktopdefault.aspx/tabid-1192/1635_read-25578
+```
+
+```{image} ../_static/img/druskat.jpg
+    :alt: Stephan Druskat
+    :class: member
+    :target: https://www.dlr.de/sc/desktopdefault.aspx/tabid-1192/1635_read-37013
+```
+
+```{image} ../_static/img/meinel.png
+    :alt: Michael Meinel
+    :class: member
+    :target: https://www.dlr.de/sc/desktopdefault.aspx/tabid-1192/1635_read-5420
+```
+
+```{image} ../_static/img/kernchen.jpg
+    :alt: Sophie Kernchen
+    :class: member
+```
+
+```{image} ../_static/img/knodel.jpg
+    :alt: Oliver Knodel
+    :class: member
+    :target: https://www.hzdr.de/db/!ContMan.Visi.Card?pUid=132739&pNid=5
+```
+
+```{image} ../_static/img/juckeland.jpg
+    :alt: Guido Juckeland
+    :class: member
+    :target: https://www.hzdr.de/db/!ContMan.Visi.Card?pUid=4930&pNid=5
+```
+
+```{image} ../_static/img/kelling.jpg
+    :alt: Jeffrey Kelling
+    :class: member
+    :target: https://www.hzdr.de/db/!ContMan.Visi.Card?pUid=5156&pNid=5
+```
+
+```{image} ../_static/img/pape.jpg
+    :alt: David Pape
+    :class: member
+    :target: https://www.hzdr.de/db/!ContMan.Visi.Card?pUid=139658&pNid=5
+```
+
+```{image} ../_static/img/bertuch.jpg
+    :alt: Oliver Bertuch
+    :class: member
+    :target: https://fz-juelich.de/profile/bertuch_o
+```
+
+</p>
+
+All outputs of the project are openly available. 
+Software is developed in the open and released under an open source license.
+Any scholarly publications, documentation and training materials is
+provided open access.
+
+```{include} ../../../GOVERNANCE.md
+```
+
+## License
+
+This project documentation is licensed under a [Creative Commons CC0 1.0 Universal (CC0 1.0) Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/legalcode). 
+
+Our logo / key visual / icon is licensed under [Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) ](https://creativecommons.org/licenses/by-nd/4.0)