Add the CITATION.cff file to take advantage of GitHub's new support for the Citation File Format

[storopoli]

This PR creates the initial draft for the CITATION.cff new file format.

Some resources for discussion:

• CFF Documentation
• CFF documentation at GitHub

Note that with every Julia new release the version value should be updated. I briefly scanned for a GitHub Actions that could automatically do that but could not find (maybe since CFF are a new thing we should have new actions becoming available in the near future).

EDIT: I think we should leave the .bib also in the repo for now.

[DilumAluthge]

Do we need the version: key? It would be easiest to just omit it.

If we are required to include the version: key, the value should match the value in the VERSION file: https://github.com/JuliaLang/julia/blob/master/VERSION

[storopoli]

Yes, we do otherwise the citation file is not valid/parsed by GitHub.

[DilumAluthge]

Darn. That means that the release managers (@KristofferC and @ararslan) would need to remember to update the version number in two different places.

Probably the easiest is to have a tiny CI job that just checks that the version: in the CITATION.cff file exactly matches the contents of the VERSION file.

[DilumAluthge]

EDIT: I think we should leave the .bib also in the repo for now.

Yeah I think that makes sense.

[ViralBShah]

Is it possible to get the rest of the bibliographic data into this format - like the journal and volume and such?

Also should we get rid of the CITATION.bib file, since this gives you an option to export a bib file? The only issue with that is that we refer to it in some places on discourse and such - but presumably we can update those links and post updated messages.

[DilumAluthge]

Also should we get rid of the CITATION.bib file, since this gives you an option to export a bib file? The only issue with that is that we refer to it in some places on discourse and such - but presumably we can update those links and post updated messages.

I was thinking keep it around. The contents of CITATION.bib are static, so can't hurt to keep it, right? At least for the short term, while we wait for the rest of the Julia ecosystem to start adopting this new standard.

[storopoli]

Is it possible to get the rest of the bibliographic data into this format - like the journal and volume and such?

Also should we get rid of the CITATION.bib file, since this gives you an option to export a bib file? The only issue with that is that we refer to it in some places on discourse and such - but presumably we can update those links and post updated messages.

Yes, we can I will add the info.

[ViralBShah]

Darn. That means that the release managers (@KristofferC and @ararslan) would need to remember to update the version number in two different places.

Probably the easiest is to have a tiny CI job that just checks that the version: in the CITATION.cff file exactly matches the contents of the VERSION file.

Is it possible to have a CI job just for releases? Running a tiny CI to check this on every commit feels a bit wasteful.

[DilumAluthge]

Darn. That means that the release managers (@KristofferC and @ararslan) would need to remember to update the version number in two different places.
Probably the easiest is to have a tiny CI job that just checks that the version: in the CITATION.cff file exactly matches the contents of the VERSION file.

Is it possible to have a CI job just for releases? Running a tiny CI to check this on every commit feels a bit wasteful.

Yeah, with Buildkite, we can have different CI for release branches vs master.

[DilumAluthge]

@storopoli Where did you see that version is required?

The CFF schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema.yaml) says that version is not required.

[storopoli]

@storopoli Where did you see that version is required?

The CFF schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema.yaml) says that version is not required.

Here: https://github.com/citation-file-format/citation-file-format/blob/main/README.md#example

If you want to make your software easily citable, you can put a file called CITATION.cff in the root of your repository. This file should provide at least the minimally necessary metadata to cite your software.

And also I did this for some repos earlier today and GitHub did not parsed if there wasn't a version in the .cff file (JuliaDataScience/JuliaDataScience@544f615)

[DilumAluthge]

@storopoli Where did you see that version is required?
The CFF schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema.yaml) says that version is not required.

Here: https://github.com/citation-file-format/citation-file-format/blob/main/README.md#example

If you want to make your software easily citable, you can put a file called CITATION.cff in the root of your repository. This file should provide at least the minimally necessary metadata to cite your software.

And also I did this for some repos earlier today and GitHub did not parsed if there wasn't a version in the .cff file (JuliaDataScience/JuliaDataScience@544f615)

Interesting. It seems to violate the schema, but 🤷

[DilumAluthge]

I think the version: v1 solution will probably be fine. The alternative (manually updating it every time) seems unpleasant.

[storopoli]

@storopoli Where did you see that version is required?
The CFF schema (https://github.com/citation-file-format/citation-file-format/blob/main/schema.yaml) says that version is not required.

Here: https://github.com/citation-file-format/citation-file-format/blob/main/README.md#example

If you want to make your software easily citable, you can put a file called CITATION.cff in the root of your repository. This file should provide at least the minimally necessary metadata to cite your software.

And also I did this for some repos earlier today and GitHub did not parsed if there wasn't a version in the .cff file (JuliaDataScience/JuliaDataScience@544f615)

Interesting. It seems to violate the schema, but 🤷

No it doesn't. It has a required: True. There are several version in the schema.

See this one: https://github.com/citation-file-format/citation-file-format/blob/main/schema.yaml#L115-L117

[DilumAluthge]

🤦 You're exactly right, I was looking at the wrong version. Thanks!

Serves me right for trying to read the schema on my phone.

[DilumAluthge]

Since there is a schema, presumably we can validate our .cff against the schema? E.g. with https://www.npmjs.com/package/yaml-schema-validator?

I don't particularly feel like opening up npm right now 😂. Maybe someone else wants to try it out?

[vtjnash]

If we decide to change the version, there is a release-checklist in the Makefile where that step would go

[ViralBShah]

I say we merge this - and we can tweak further later on as necessary.

[ViralBShah]

The github generated bibtex has some ways to go. I think we'll have to keep CITATION.bib for a while!

[storopoli]

At least we have the dropdown to cite this repo:

[arfon]

The github generated bibtex is terrible. I think we'll have to keep CITATION.bib for a while!

Feel free to open an issue on https://github.com/citation-file-format/ruby-cff reporting any issues with the bibtex 😁

[arfon]

The github generated bibtex is terrible. I think we'll have to keep CITATION.bib for a while!

Feel free to open an issue on https://github.com/citation-file-format/ruby-cff reporting any issues with the generated bibtex output.

[ViralBShah]

The main thing is all the other metadata about the article that exists in our CITATION.cff file (like volume, pages, etc.) doesn't get incorporated into the generated BibTeX. Also it makes it an @misc bibtex entry, but we really want @article. I don't know enough about the cff format to be certain if we have done things right - so not filing an issue myself. But perhaps someone else may be better positioned to do that.

[arfon]

Got it, thanks! CFF v1.2.0 will be introducing the concept of a preferred-citation which can be an article rather than a (@misc) citation snippet for the software.

[StefanKarpinski]

To clarify why @misc is inappropriate for us, there is an actual academic publication that should be cited when citing this project, rather than directly citing the repository or the software. I suspect this is the case for many other Julia packages as well, and it is probably not uncommon in other language ecosystems. The CITATION.bib file in the repo is how we ideally want our generated BibTeX citation data to look.