Add support for CITATION.cff format

[c-martinez]

This PR addresses #1469

I am not very experienced with R, but am a big supporter of CITATION.cff and encourage its adoption at every opportunity, so this looked like a good opportunity to contribute. I've asked a colleague (@PabRod) to review my code before sending this PR.

I don't think this is perfect, but I think it works and am happy to improve it as necessary.

[PabRod]

Some context

Citation File Format (CFF) files are plain text files containing citation info in both a machine- and human-readable manner. This format is endorsed, among others, by:

• GitHub, where it even renders a citation side menu (see more here)
• Zenodo, where it's used to autocomplete the repository fields
• Zotero

All context

Want to know even more? Please visit the Citation File Format website.

[jennybc]

An R package on which the proposed use_cff() had been used does not pass R CMD check cleanly:

N  checking top-level files ...
   Non-standard file/directory found at top level:
     ‘CITATION.cff’
✔  checking for left-over files ... OK
✔  checking index information
N  checking package subdirectories ...
   Found the following CITATION file in a non-standard place:
     CITATION.cff
   Most likely ‘inst/CITATION’ should be used instead.

Are there existing R packages that actually use this? As the message above says, there's already a strong R convention for using inst/CITATION, which is then supported by the utils::citation() function.

If the CITATION.cff file appears below inst/ does it still enjoy the favorable treatment from GitHub?

[jennybc]

This needs to be fleshed out.

[c-martinez]

If the CITATION.cff file appears below inst/ does it still enjoy the favorable treatment from GitHub?

Unfortunately, it looks like the CFF file needs to be on the root directory:

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files

[olivroy]

You can use use_template(ignore = TRUE) to add to .Rbuildignore

[jennybc]

But if we .Rbuildignore this new file, what really is the point? It would not make it on to a user's system.

[jennybc]

I went to one of the links above and found interesting info about "Other citation files":

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#other-citation-files

GitHub already looks for the inst/CITATION file that is the convention in R packages!

I'm starting to think that CITATION.cff may not be compelling for R packages, given our pre-existing facilities for this.

[c-martinez]

If inst/CITATION is already the standard for R, maybe indeed this doesn't have much added value.

Maybe a more useful thing to do would be to document this is the preferred way to cite software written in R (for example in The Turing Way section on software citation).

And perhaps it is worth checking it is possible to convert one format into the other (with cffconvert?) if for whatever reason someone preferred to use CFF format?

[jennybc]

Yeah I think the case for CITATION.cff for packages is hard to make as it stands, since it's basically competing with an existing standard that is supported by both the base language (inst/CITATION + utils::citation()) and by GitHub.

So I think you make good points about the Turing Way guide and raising awareness of cffconvert, but I don't see a clear action item for usethis itself at this time.

[PabRod]

Dear @jennybc,

@c-martinez asked me to provide some answers to your questions.

TL;DR

CITATION.cff adds a functionality on top of inst/CITATION that some users want. Examples are integration with Zenodo, the Research Software Directory and preferential treatment in GitHub.

Details

Looking at the whole conversation, I feel there is some misunderstanding. It is not our purpose to replace nor compete against R's inst/CITATION, but to allow users who want to additionally use a CITATION.cff file to do it comfortably.

This is why CITATION.cff's effect is additive and non-destructive. Although it may look redundant, it adds a very desirable functionality: rendering a mini menu with a copy-pastable citation string on the GitHub project's page (see example below, taken from CRAN's kinematics).

As far as I know GitHub didn't implement this for inst/CITATION, nor any other citation system than CFF.

Why is this important?

Enabling a user-friendly interface for citing code in the world's largest code repository is a huge step toward recognizing research software. We know R, RStudio, and Posit also believe in this mission.

Answers to specific questions

• "But if we .Rbuildignore this new file, what really is the point? It would not make it on to a user's system."
  • CITATION.cff's main role actually takes place on GitHub. Shipping it with the package doesn't add too much value. Even if it did, it corresponds to R core maintainers, not to us, to add it to the white list of accepted package files.
• "GitHub already looks for the inst/CITATION file that is the convention in R packages!".
  • GitHub treats CITATION.cff preferentially. Compare the left side menu of usethis and kinematics. Only the one with CITATION.cff has the field Cite this repository enabled by GitHub. Furthermore, see for instance projr. It contains both inst/CITATION and CITATION.cff, but GitHub renders its citation menu only from the cff one.
• "Are there existing R packages that actually use this?"
  • A GitHub query for CITATION.cff among R projects returns more than a thousand hits. See for instance:
    • projr
    • magpie
    • remind

Action points

We kindly ask you to reconsider reopening this pull request. We are open to highlight the priority of inst/CITATION by, for instance:

• Mentioning it in the documentartion.
• Throwing a warning.
• Using inst/CITATION to pre-fill the CITATION.cff fields.

And of course, to address any other required edition.

Thank you for your time and consideration!