Create CITATION.cff

[BenjaminRodenberg]

Github added support for citation files (see https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files). This PR provides a draft for such a file.

• I followed the authors list from the FEniCS adapter paper [1].
• I used the abstract from [1] (-> question here: Should we modify the abstract that it fits for the code and not for the paper?)
• I used the keyword from [1]
• I used the title of [1] (-> question here: Should we modify the title to "FEniCS-preCICE adapter" which is the name of the software. See https://github.com/precice/fenics-adapter/blob/develop/README.md#fenics-precice-adapter)
• I used version 1.0.1 and the corresponding date (https://github.com/precice/fenics-adapter/releases/tag/v1.0.1), since this is used in [1] (-> question here: Should we always point to the most recent version?)

As far as I understand the idea of the CITATION.cff file is to point to the code. There is the possibility to add a DOI. I am not 100% sure whether we should refer to [1] or generate a DOI on zenodo and refer to the code (see https://guides.github.com/activities/citable-code/). My questions above are mainly related to this question "should we refer to the paper or to the code?". But there is a possibility to add further references. See https://github.com/citation-file-format/citation-file-format#references-optional.

My current proposal: Let's point to [1] and inherit everything from there. This keeps maintainment low, since otherwise we would have to create a new zenodo entry for each release. Additionally, there is some danger that in the end there are too many possibilities for citing.

@richahert @ajaust: please also check this quickly, since your names are on the list. I can also trigger you again before merging this PR. I expect some discussion until we finally converge (Unfortunatelly cannot assign you as reviewers).

References

[1] https://arxiv.org/pdf/2103.11191.pdf

Todos

• Agree on an approach
• Get positive review from all authors
• Check Button again. Is it a bug? Create CITATION.cff #137 (comment)

[BenjaminRodenberg]

From https://github.com/citation-file-format/citation-file-format#file-structure:

• optionally, a list of references which should be cited in different use cases or scopes, e.g., a software paper describing the abstract concepts of the software (references).

As far as I understand [1] should go under references. But whether we want to follow this standard or not is up to discussion. The concerns mentioned above are from my point of view still valid.

Using the reference format for [1] paper would add the following:

references:
  - scope: "Cite this paper when you use the software"
    type: article
    authors: 
      -
        affiliation: "Technical University of Munich"
        family-names: Rodenberg
        given-names: Benjamin
        orcid: "https://orcid.org/0000-0002-3116-0133"
      -
        affiliation: "University Stuttgart"
        family-names: Desai
        given-names: Ishaan
        orcid: "https://orcid.org/0000-0002-2552-7509"
      -
        family-names: Hertrich
        given-names: Richard
        orcid: "https://orcid.org/0000-0003-1722-2841"
      -
        affiliation: "University of Stuttgart"
        family-names: Jaust
        given-names: Alexander
        orcid: "https://orcid.org/0000-0002-6082-105X"
      -
        affiliation: "University of Stuttgart"
        family-names: Uekermann
        given-names: Benjamin
        orcid: "https://orcid.org/0000-0002-1314-9969"
    abstract: ...
    year: 2021
    url: "https://arxiv.org/abs/2103.11191"
    title: "FEniCS-preCICE: Coupling FEniCS to other Simulation Software"

Note: Using references gives us the possibility to also refer to the preCICE tutorials, reference paper, other adapters etc., but probably also will cause a lot of maintainment. I personally like the scope key.

[IshaanDesai]

Github added support for citation files (see https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files). This PR provides a draft for such a file.

* I followed the authors list from the FEniCS adapter paper [1].

* I used the abstract from [1] (-> question here: Should we modify the abstract that it fits for the code and not for the paper?)

I think the abstract of the paper is good enough for now. As the journal is SoftwareX, the abstract does not seem too formal to me. It would also then be consistent

* I used the title of [1] (-> question here: Should we modify the title to "FEniCS-preCICE adapter" which is the name of the software.

Changing the title of the document to match with the code title seems like an unnecessary change. To me the code title is a nice software package title and the paper title is a description of it

* I used version 1.0.1 and the corresponding date (https://github.com/precice/fenics-adapter/releases/tag/v1.0.1), since this is used in [1] (-> question here: Should we always point to the most recent version?)

I think we should point to the version which we talk about in the publication. I can estimate that having a different latest version than the one in the cite-able publication is something that every scientific code will encounter in the near future.

My current proposal: Let's point to [1] and inherit everything from there. This keeps maintainment low, since otherwise we would have to create a new zenodo entry for each release. Additionally, there is some danger that in the end there are too many possibilities for citing.

Agree to this 👍

[IshaanDesai]

I noticed that the button View citation file is not working right now. Is this supposed to already work?

[BenjaminRodenberg]

I noticed that the button View citation file is not working right now. Is this supposed to already work?

Good observation! Looks to me like a bug. Nice that the integration already works branch specific, but seems like some internal wiring is missing, if the branch is not the main branch? Let's see what happens, if we merge this PR. We can then report this issue somewhere. I just checked the button on https://github.com/citation-file-format/citation-file-format and it works as expected.

[BenjaminRodenberg]

The .bib reveals some problems with the current approach:

@misc{Rodenberg_FEniCSpreCICE_Coupling_FEniCS_2021,
author = {Rodenberg, Benjamin and Desai, Ishaan and Hertrich, Richard and Jaust, Alexander and Uekermann, Benjamin},
month = {1},
title = {FEniCS-preCICE: Coupling FEniCS to other Simulation Software},
url = {https://github.com/precice/fenics-adapter},
year = {2021}
}

• month is extracted from the date-released (I assume). The paper is from March, the code version is from March. So there is a gap that we cannot generally avoid.
• The url points to the repository, not to the arXiv paper.

I will draft the more complicated approach from above on another branch and take a look at the results from easier comparison.

[BenjaminRodenberg]

I will draft the more complicated approach from above on another branch and take a look at the results from easier comparison.

Did a quick draft on https://github.com/precice/fenics-adapter/tree/BenjaminRodenberg-add-citation-long.

Unfortunately, it does not load. Seems to be another bug:

[IshaanDesai]

Looks like some proposed features are still in beta version

[BenjaminRodenberg]

https://github.com/precice/fenics-adapter/tree/BenjaminRodenberg-add-citation-long loads now, but the bibtex just shows the top level resource:

@misc{Rodenberg_FEniCSpreCICE_adapter_2021,
author = {Rodenberg, Benjamin and Desai, Ishaan and Hertrich, Richard and Uekermann, Benjamin},
month = {1},
title = {FEniCS-preCICE adapter},
url = {https://github.com/precice/fenics-adapter},
year = {2021}
}

I guess the question is now: Do we want people to cite the code or the paper? Currently the long version provided on https://github.com/precice/fenics-adapter/tree/BenjaminRodenberg-add-citation-long does bring additional value from my perspective, if you don't see the additional references block at all.

[ajaust]

I have not had time to look into this in detail, but maybe on could check with the citation file format project what they recommend or what this ccf files are meant for? Quite some projects also have both, a publication and a Zenodo entry for the release. One example on Zenodo would be Dumux. They currently have an overview paper for the current v3 of DuMuX and an Zenodo entry for the minor versions. Is this something you want to have for the FEniCS adapter?

Maybe on could ask the people to cite the paper as broader reference of the adapter and Zenodo for referring to the actual release which helps also with the reproducibility?!

Why do you want to use this CCF file at the moment? Wouldn't a "How to cite" section in the README enough?

[BenjaminRodenberg]

I have not had time to look into this in detail, but maybe on could check with the citation file format project what they recommend or what this ccf files are meant for? Quite some projects also have both, a publication and a Zenodo entry for the release. One example on Zenodo would be Dumux. They currently have an overview paper for the current v3 of DuMuX and an Zenodo entry for the minor versions. Is this something you want to have for the FEniCS adapter?

Maybe on could ask the people to cite the paper as broader reference of the adapter and Zenodo for referring to the actual release which helps also with the reproducibility?!

I think the preferred-citation key of the upcoming 1.2.0 of cff will allow us to implement this workflow. I am already using this key in 10de268. But until cff v1.2.0 is released I would suggest to stick to the shorter version that directly points to the arXiv paper provided via this PR.

A zenodo release for each (major/minor/bugfix) release is something we can still do and which is more or less independent of the cff file (we only have to add another key). One thing that's tricky here: Who is an author of the code? Are there any guidelines? @ajaust and I already discussed this personally.

I also see some benefits w.r.t reproducibility, if we provide an independent zenodo entry for each release. Thanks for the the DuMuX example! I also like how zenodo deals with different versions and provides different DOIs. Related comment from the cff developers here: citation-file-format/citation-file-format#254 (comment)

Why do you want to use this CCF file at the moment? Wouldn't a "How to cite" section in the README enough?

Main motivation here is the better visibility of the "Cite this repository" button on github. This additionally offers bibtex export, which is useful, in my opinion. The "How to cite" section in the README is something we already use. This is ok, but not a standardized approach.

[IshaanDesai]

Overall looks good, I am not sure if the persistent bugs with the GUI would cause problems later on.

[uekerman]

Why do you want to use this CCF file at the moment? Wouldn't a "How to cite" section in the README enough?

This PR was also meant as a "let's give this a try and see how it works". If we see in the FEniCS adapter that this approach is great, we could carry it over to all other adapters and preCICE. The PR does not mean that we are already convinced by the
feature. "Try first in an adapter repo" is common approach for us 😁

[IshaanDesai]

Just a note that we should change the reference of the citation from the preprint to the published version of the paper: https://doi.org/10.1016/j.softx.2021.100807

[IshaanDesai]

The button View Citation File is now working. We can merge this after changing the citation from the preprint to the published version of the code.

[BenjaminRodenberg]

I updated the information to the version published in SoftwareX and added the DOI + a DOI badge. From my perspective it is now ready to go.

In the future it might be more appropriate to publish each version on zenodo and also link to the zenodo release (for example, if a repo does not offer a paper precice/fenicsx-adapter#5). Another problem I see with citing the paper is that the paper points to v1.2.0 and we are already now at v1.3.0. At the current point in time this is ok, but it will become worse in the future.

Summary: For this repository citing the paper is fine at the current point in time, but we will have to revisit this approach and it might not fit for other repositories.

[uekerman]

I agree with only pointing to the paper here.

Zenodo / DaRUS, I see as an option if we don't have a paper for a repo or to point to a specific version. For the latter, however, we already have the distribution. So, still unclear to me whether we want an additional entry in the long run. There, we should agree on a general strategy applicable to all repos under the preCICE organization.