feat: distinguish between author and publication_author

Author: a.pirogov

.somesy.toml

@@ -54,6 +54,8 @@ contribution_begin = "2023-06-01"
 contribution_end = "2023-06-30"
 contribution_types = ["ideas"]
 
+publication_author = true
+
 [[project.people]]
 family-names = "Sandfeld"
 given-names = "Stefan"
@@ -62,6 +64,8 @@ orcid = "https://orcid.org/0000-0001-9560-4728"
 
 contribution_types = ["fundingFinding"]
 
+publication_author = true
+
 [config]
 no_sync_cff = false
 cff_file = "CITATION.cff"

CITATION.cff

@@ -11,14 +11,22 @@ keywords:
 - metadata
 - FAIR
 authors:
-- email: m.soylu@fz-juelich.de
-  family-names: Soylu
+- orcid: https://orcid.org/0000-0003-2637-0432
+  email: m.soylu@fz-juelich.de
   given-names: Mustafa
-  orcid: https://orcid.org/0000-0003-2637-0432
-- email: a.pirogov@fz-juelich.de
-  family-names: Pirogov
+  family-names: Soylu
+- orcid: https://orcid.org/0000-0002-5077-7497
+  email: a.pirogov@fz-juelich.de
   given-names: Anton
-  orcid: https://orcid.org/0000-0002-5077-7497
+  family-names: Pirogov
+- email: v.hofmann@fz-juelich.de
+  orcid: https://orcid.org/0000-0002-5149-603X
+  family-names: Hofmann
+  given-names: Volker
+- email: s.sandfeld@fz-juelich.de
+  orcid: https://orcid.org/0000-0001-9560-4728
+  family-names: Sandfeld
+  given-names: Stefan
 contact:
 - email: m.soylu@fz-juelich.de
   family-names: Soylu

README.md

@@ -71,7 +71,7 @@ keywords = ["some", "descriptive", "keywords"]
 license = "MIT"
 repository = "https://github.com/username/my-amazing-project"
 
-# This is you, the proud author of your project
+# This is you, the proud author of your project:
 [[project.people]]
 given-names = "Jane"
 family-names = "Doe"
@@ -80,12 +80,14 @@ orcid = "https://orcid.org/0000-0000-0000-0001"
 author = true      # is a full author of the project (i.e. appears in citations)
 maintainer = true  # currently maintains the project (i.e. is a contact person)
 
-# this person is a acknowledged contributor, but not author or maintainer:
+# this person is an acknowledged contributor, but not author or maintainer:
 [[project.people]]
 given-names = "Another"
 family-names = "Contributor"
 email = "a.contributor@example.com"
 orcid = "https://orcid.org/0000-0000-0000-0002"
+# ... but for scientific publications, this contributor should be listed as author:
+publication_author = true
 
 [config]
 verbose = true     # show detailed information about what somesy is doing
@@ -151,17 +153,16 @@ Here is an overview of all the currently supported files and formats.
 | Input Formats  | Status | | Target Formats                | Status |
 | -------------- | ------ |-| ----------------------------- | ------ |
 | (.)somesy.toml | ✓      | | pyproject.toml _(poetry)_     | ✓      |
-| pyproject.toml | ✓(1.)  | | pyproject.toml _(setuptools)_ | ✓(2.)  |
-| package.json   | ✓      | | package.json                  | ✓(3.)  |
+| pyproject.toml | ✓      | | pyproject.toml _(setuptools)_ | ✓(1.)  |
+| package.json   | ✓      | | package.json                  | ✓(2.)  |
 |                |        | | CITATION.cff                  | ✓      |
-|                |        | | codemeta.json                 | ✓(4.)  |
+|                |        | | codemeta.json                 | ✓(3.)  |
 
 **Notes:**
 
-1. information must be placed inside a `tool.somesy` section (as explained above)
-2. note that `somesy` does not support setuptools *dynamic fields*
-3. `package.json` only supports one author, so `somesy` will pick the *first* listed author
-4. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
+1. note that `somesy` does not support setuptools *dynamic fields*
+2. `package.json` only supports one author, so `somesy` will pick the *first* listed author
+3. unlike other targets, `somesy` will *re-create* the `codemeta.json` (i.e. do not edit it by hand!)
 
 <!-- --8<-- [end:quickstart] -->
 

codemeta.json

@@ -11,14 +11,26 @@
     "audience": [
         {
             "@type": "Audience",
-            "audienceType": "Science/Research"
+            "audienceType": "Developers"
         },
         {
             "@type": "Audience",
-            "audienceType": "Developers"
+            "audienceType": "Science/Research"
         }
     ],
     "author": [
+        {
+            "@id": "https://orcid.org/0000-0002-5149-603X",
+            "@type": "Person",
+            "familyName": "Hofmann",
+            "givenName": "Volker"
+        },
+        {
+            "@id": "https://orcid.org/0000-0001-9560-4728",
+            "@type": "Person",
+            "familyName": "Sandfeld",
+            "givenName": "Stefan"
+        },
         {
             "@id": "https://orcid.org/0000-0003-2637-0432",
             "@type": "Person",
@@ -49,14 +61,14 @@
             "identifier": "'version':",
             "name": "'version':",
             "runtimePlatform": "Python 3",
-            "version": "'^0.7.0'}"
+            "version": "'^1.9.2'}"
         },
         {
             "@type": "SoftwareApplication",
             "identifier": "'version':",
             "name": "'version':",
             "runtimePlatform": "Python 3",
-            "version": "'^1.9.2'}"
+            "version": "'^0.7.0'}"
         },
         {
             "@type": "SoftwareApplication",

docs/manual.md

@@ -406,3 +406,21 @@ hood, you use `somesy` (or anything like it) or not - they can use the
 corresponding files they already know to get the information they need.
 So there is no "risk" involved in adopting `somesy`, because it does not try to
 abolish any other formats or standards or becoming such.
+
+### In my project, the effective authors and the publication authors are not the same! What to do?
+
+The `author` flag in `somesy` is intended to mark people who significantly contributed
+to the project in a hands-on way and are closely familiar with details, i.e. can answer
+specific questions. A reason to stick with this strict understanding of "author"
+is that a user will be usually interested in contacting such a person to help
+them with problems.
+
+However, we are aware that acknowledgement practices in different scientific
+communities vary and current practices in academic publication do not allow for
+sufficiently granular distinction of contributor roles.
+Even though the proper solution to problem would be improving community practices,
+`somesy` supports the `publication_author` flag, that can be set independently of the
+`author` flag and will make sure that certain contributors **will** appear as authors
+in an academic citation context (i.e. reflected in the `CITATION.cff` file, which can be
+used for [Zenodo publications](https://docs.software-metadata.pub/en/latest/tutorials/automated-publication-with-ci.html)), but **will not** appear as authors in a technical context
+(such as the metadata in a software registry like [PyPI](https://pypi.org)).

src/somesy/cff/writer.py

@@ -6,7 +6,7 @@
 from cffconvert.cli.create_citation import create_citation
 from ruamel.yaml import YAML
 
-from somesy.core.models import Person
+from somesy.core.models import Person, ProjectMetadata
 from somesy.core.writer import ProjectMetadataWriter
 
 
@@ -64,6 +64,12 @@ def save(self, path: Optional[Path] = None) -> None:
         path = path or self.path
         self._yaml.dump(self._data, path)
 
+    def _sync_authors(self, metadata: ProjectMetadata) -> None:
+        """Ensure that publication authors are added all into author list."""
+        self.authors = self._sync_person_list(
+            self.authors, metadata.publication_authors()
+        )
+
     @staticmethod
     def _from_person(person: Person):
         """Convert project metadata person object to cff dict for person format."""
@@ -74,6 +80,7 @@ def _from_person(person: Person):
                 "contribution_begin",
                 "contribution_end",
                 "author",
+                "publication_author",
                 "maintainer",
             },
             by_alias=True,  # e.g. family_names -> family-names, etc.

src/somesy/core/models.py

@@ -274,9 +274,15 @@ class Person(SomesyBaseModel):
     author: Annotated[
         bool,
         Field(
-            description="Indicates whether the person is an author of the project (i.e. for citations)."
+            description="Indicates whether the person is an author of the project (i.e. significant contributor)."
         ),
     ] = False
+    publication_author: Annotated[
+        Optional[bool],
+        Field(
+            description="Indicates whether the person is to be listed as an author in academic citations."
+        ),
+    ]
     maintainer: Annotated[
         bool,
         Field(
@@ -303,6 +309,17 @@ class Person(SomesyBaseModel):
         Optional[date], Field(description="Ending date of the contribution.")
     ]
 
+    @root_validator
+    def author_implies_publication(cls, values):
+        """Ensure consistency of author and publication_author."""
+        if values["author"]:
+            # NOTE: explicitly check for False (different case from None = missing!)
+            if values["publication_author"] == False:
+                msg = "Combining author=true and publication_author=false is invalid!"
+                raise ValueError(msg)
+            values["publication_author"] = True
+        return values
+
     # helper methods
 
     @property
@@ -394,9 +411,16 @@ def at_least_one_author(cls, people):
     )
 
     def authors(self):
-        """Return people marked as authors."""
+        """Return people explicitly marked as authors."""
         return [p for p in self.people if p.author]
 
+    def publication_authors(self):
+        """Return people marked as publication authors.
+
+        This always includes people marked as authors.
+        """
+        return [p for p in self.people if p.publication_author]
+
     def maintainers(self):
         """Return people marked as maintainers."""
         return [p for p in self.people if p.maintainer]

src/somesy/core/writer.py

@@ -183,6 +183,14 @@ def _sync_person_list(self, old: List[Any], new: List[Person]) -> List[Any]:
         old_people: List[Person] = self._parse_people(old)
         return self._merge_person_metadata(old_people, new)
 
+    def _sync_authors(self, metadata: ProjectMetadata) -> None:
+        """Sync output file authors with authors from metadata.
+
+        This method is existing for the publication_author special case
+        when synchronizing to CITATION.cff.
+        """
+        self.authors = self._sync_person_list(self.authors, metadata.authors())
+
     def sync(self, metadata: ProjectMetadata) -> None:
         """Sync output file with other metadata files."""
         self.name = metadata.name
@@ -194,7 +202,7 @@ def sync(self, metadata: ProjectMetadata) -> None:
         if metadata.keywords:
             self.keywords = metadata.keywords
 
-        self.authors = self._sync_person_list(self.authors, metadata.authors())
+        self._sync_authors(metadata)
         self.maintainers = self._sync_person_list(
             self.maintainers, metadata.maintainers()
         )