Add CITATION.cff file

[mhucka]

A file in CITATION File Format (CITATION.cff) can be placed at the top level of a GitHub repo to provide machine-readable citation information that helps users correctly cite software. When it detects a CITATION.cff file in a repository, GitHub adds a button to the upper right sidebar that lets users copy a formatted citation.

I generated this particular CITATION.cff file mostly by hand, with a little initial help from Citation.js.

This commit also includes a GitHub Actions workflow to update the release version & date in the CITATION.cff file automatically when a new software release is made on GitHub. This solves the problem of keeping the version & date in the file in sync with releases. Removed the workflow, after discussions during review revealed a problem that still needs resolving.

@mpharrigan and @tanujkhattar: the abstract and the list of keywords in the CITATION.cff file could use a review. I gave it a good try but there may still be errors.

[mpharrigan]

does this commit directly to main? or open a PR?

[mhucka]

It commits directly to main. This way, as soon as the release is done, the citation.cff file gets updated, and shortly thereafter GitHub will pick up the changes and update the "Cite this repository" contents.

[mhucka]

does this commit directly to main? or open a PR?

(Should I add comments in the file to make that more clear?)

[mpharrigan]

Yeah, maybe others will have the same question as me.

This does set up a weird circular problem where the tagged commit will never contain the citation.cff file that references it, but I don't think there's any way around that

[mhucka]

This does set up a weird circular problem where the tagged commit will never contain the citation.cff file that references it, but I don't think there's any way around that

@mpharrigan (Face palm.) I … didn't think of that. I was too focused on updating the info on GitHub and forgot about the implications for doing it as a response to a release, rather than a precursor to a release.

What if, instead of triggering on a release event, it triggered when a tag was created? Based on how-to-cut-a-release.md, it looks like triggering on a tagging event would do it, as that precedes the step to package the release. Do you guys tag for any except releases? (If so, we could filter based on an appropriate tag pattern, to skip non-release tagging events.)

[mhucka]

For the time being, I'm going to remove the workflow, and just add the .cff and the readme addition. The auto-updater is not essential and can be sorted out later.

[mpharrigan]

will the citation button generate the same bibtex as that included in (added to) the readme?

[mhucka]

will the citation button generate the same bibtex as that included in (added to) the readme?

Good question. The BibTeX in the readme file came from arXiv itself, except for the doi field, which I added manually because it's not uncommon in BibTeX styles. (I don't know why arXiv doesn't provide it.)

First, I see that the type of the preferred-citation should be "misc" and not "article". After fixing that, I tested GitHub's conversion of CITATION.cff to BibTeX by adding the CITATION.cff file to my fork, then using GitHub's button. Here's the output:

@misc{Harrigan_Expressing_and_Analyzing_2024,
  author = {Harrigan, Matthew P. and Khattar, Tanuj and Yuan, Charles and Peduri, Anurudh and Yosri, Noureldin and Malone, Fionn D. and Babbush, Ryan and Rubin, Nicholas C.},
  doi = {10.48550/arXiv.2409.04643},
  title = {{Expressing and Analyzing Quantum Algorithms with Qualtran}},
  url = {https://arxiv.org/abs/2409.04643},
  year = {2024}
}

You can see it drops the fields eprint, archivePrefix and primaryClass, but otherwise is the same (well, authors names are put in an alternate but equivalent form). Now, the thing is, archivePrefix and primaryClass are not (as far as I can tell) used by any BibTeX class; the only field that gets any use is eprint, and even that is not universal. ArXiv's documentation lists some BST files and extensions to support eprint.

The more I look at this, the more I think we should remove the archivePrefix and primaryClass from the BibTeX on the front. It doesn't add anything and may instead just add trouble.

So that leaves the missing eprint field. CITATION.cff doesn't define such a field for the citations, but it does have a way to add additional identifiers and keywords. It's a bit of a long shot, but I tried using that to define it this way:

  ...
  identifiers:
    - description: arXiv identifier for the submission
      value: 2409.04643
      type: other
  keywords:
    - quant-ph

Unfortunately, GitHub does not seem to produce any different output.

How significant would be the lost of the eprint field?

[mpharrigan]

Thanks for checking. If we can't get the eprint field, then so be it