Consider adopting cff citation file format

[fcooper8472]

This comes with some built-in GitHub support and looks as though it's becoming a standard:

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

[mirams]

I agree a bit with @MichaelClerx about needing new tools just to read what the citation is being quite an annoying thing. If we do it I would suggest leaving the existing very understandable CITATION.txt as well!

[fcooper8472]

I'm not sure what you mean by needing new tools?

The file format is plaintext so you can just read it if you want to. But GitHub will also allow you to get APA or BibTeX from a dropdown box on the repository homepage.

I might be misunderstanding though - what tools are you referring to?

[mirams]

Well I put the recommended file in https://github.com/ModellingWebLab/chaste-codegen/ and it ends up looking like this because they want a software (Zenodo) citation as well as a preferred (publication) citation. Yeah, the github button works to get APA or bibtex, but you obviously can't just copy and paste this if you have the code on your computer, you have to rely on github clicking specifically to export the .bib entry (or otherwise download some cff-lib type thing to do it that github uses behind the scenes).

Whereas if you wanted to be relying on tools to get the citation readable you could just have the .bib entry and then generate all other citation styles direct from that rather than inventing another file format. It's designed specifically for this question of software and another citation I guess.

So in summary, whilst it is nice to have github clicky gui ways of getting a citation, I don't think that's necessarily 'better' than having the citations you'd want in a plain text and readable format like we do now! Plus we get the flexibility of listing more than one and a bit of advice about what to cite.

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:

- family-names: "Hendrix"
  given-names: "Maurice"
  orcid: "https://orcid.org/0000-0002-6621-7996"
- family-names: "Clerx"
  given-names: "Michael"
  orcid: "https://orcid.org/0000-0003-4062-3061"
- family-names: "Tamuri"
  given-names: "Asif U."
  orcid: "https://orcid.org/0000-0001-6633-3789"
- family-names: "Keating"
  given-names: "Sarah M."
  orcid: "https://orcid.org/0000-0002-3356-3542"
- family-names: "Johnstone"
  given-names: "Ross H."
- family-names: "Cooper"
  given-names: "Jonathan"
  orcid: "https://orcid.org/0000-0001-6009-3542"
- family-names: "Mirams"
  given-names: "Gary R."
  orcid: "https://orcid.org/0000-0002-4569-4312"

title: "chaste-codegen"
version: 0.10.4
doi: 10.5281/zenodo.8207994
date-released: 2023-08-02
url: "https://github.com/ModellingWebLab/chaste-codegen"

preferred-citation:
  type: article
  authors:

  - family-names: "Hendrix"
    given-names: "Maurice"
    orcid: "https://orcid.org/0000-0002-6621-7996"
  - family-names: "Clerx"
    given-names: "Michael"
    orcid: "https://orcid.org/0000-0003-4062-3061"
  - family-names: "Tamuri"
    given-names: "Asif U."
    orcid: "https://orcid.org/0000-0001-6633-3789"
  - family-names: "Keating"
    given-names: "Sarah M."
    orcid: "https://orcid.org/0000-0002-3356-3542"
  - family-names: "Johnstone"
    given-names: "Ross H."
  - family-names: "Cooper"
    given-names: "Jonathan"
    orcid: "https://orcid.org/0000-0001-6009-3542"
  - family-names: "Mirams"
    given-names: "Gary R."
    orcid: "https://orcid.org/0000-0002-4569-4312"

  title: "cellmlmanip and chaste_codegen: automatic CellML to C++ code generation with fixes for singularities and automatically generated Jacobians"
  journal: "Wellcome Open Research"
  year: 2022
  volume: 6
  start: 261
  doi: 10.12688/wellcomeopenres.17206.2

[fcooper8472]

It looks as though GH also looks for other files: "GitHub will link to these files in the Cite this repository prompt, but will not attempt to parse them into other citation formats."

CITATION
CITATIONS
CITATION.bib
CITATIONS.bib
CITATION.md
CITATIONS.md

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

Currently we use CITATION.txt.

Perhaps we should keep our existing file, but remove the extension so GitHub sees it, and also create a cff?

Let's discuss at the next meeting.

[mirams]

Sounds good to me

[mirams]

Tweaked the CITATION.txt to CITATION.md in the draft pull request above. Todo - also add a CITATION.cff which will point to the latest Zenodo release (this gets very circular and annoying and you have to reserve DOIs to have them in the code before they get archived and things like this!)

[mirams]

Pull request updated with a CITATION.cff file that gives the Zenodo link and the preferred citation seems to export on Github to APA or BibTeX fine.