Add a `CITATION.CFF` file

[meliache]

That's a machine-readable format for citations which is supported by github and would add a Cite this repository button to the github interface. For why else it's useful see https://citation-file-format.github.io.

There's already a CITATION.rst file and I wouldn't remove that because I assume that for many iminuit users the sphinx/readthedocs page is their starting page, as it's the top result in google. Not sure if there's a way to integrate both without duplicating the information.

I found that scikit-hep projects the CITATION.cff doesn't seem widely adopted yet, so far I only found such a file for the hist package (but I didn't check all repositories). But I think it's a good idea and would propose to push its usage.

[HDembinski]

Thank you, this is a very good suggestion. I will propose this to the other maintainers, too.

[henryiii]

@matthewfeickert's been working on this:

• Add CITATION.cff Citation File Format file to repo pyhf#1541
• docs: Add CITATION.cff Citation File Format file pyhf#1551
• [DOCS] Add citation metadata wtih CITATION.cff hist#413
• Add citation metadata wtih CITATION.cff uproot5#604
• Add CITATION.cff template to developer pages scikit-hep.github.io#234
• Consider removing version information from CITATION.cff pyhf#1891

Ideally we need a nice guide on scikit-hep.org/developer on adding these (including using the tool @matthewfeickert's been using to check them). It's not something I think we can add to cookie (though scientific-python/cookie#93 was an attempt) because you need to fill it out with ORCID's and such, and that would make the cookie either ask an unreasonable number of questions, or have half filled out files you have to know about. However, it likely could be added to repo-review, and I've even marked an issue scientific-python/repo-review#13 about it for the PyHEP Hackashop, that would be a good thing for someone to add.

[henryiii]

Is there a way to include a CITATION.cff into RST docs? That would be very interesting. This sounds relevant: https://bytemeta.vip/repo/citation-file-format/citation-file-format/issues/356 - seems to have been attempted then abandoned / delayed, perhaps: https://gitlab.hzdr.de/hcdc/hereon-netcdf/sphinxext

[matthewfeickert]

Also

• docs: Add CITATION.cff Citation File Format file vector#243

:)

Is there a way to include a CITATION.cff into RST docs?

Not sure off the top of my head, but given that he invited pings in scikit-hep/vector#238 (comment) we could ask @sdruskat (:wave:).

[HDembinski]

I think we need a script that generates the file to automatically on each release to update the version number and the author list.

[HDembinski]

Closing this after adding CITATION.CFF. I wrote a CITATION.CFF by hand after all. Adding CITATION.CFF has some drawbacks for me. If CITATION.CFF is present, Zenodo uses it instead of generating metadata from the repository. I liked that Zenodo automatically added new contributors to the author list. Now I have to take care of that myself and need to automate this.

[sdruskat]

Not sure off the top of my head, but given that he invited pings in scikit-hep/vector#238 (comment) we could ask @sdruskat (👋).
@matthewfeickert Sorry I didn't pick this up earlier. I can't say what happened to the CFF-embedding for RST, but perhaps @Chilipp can say more?

I liked that Zenodo automatically added new contributors to the author list. Now I have to take care of that myself and need to automate this.

Yes, that's true, although the automated metadata from the GitHub API that Zenodo pulls without a CFF file has some drawbacks itself, such as the potential discrepancy between contributors and authors.

Perhaps of interest: I'm part of a project (HERMES) that aims to automate the publication process and adding metadata from different sources, including git metadata (e.g., contributors).

[eduardo-rodrigues]

Good morning. Yes indeed there are pros and cons. In the end I still went for a CITATION.CFF file because it provides quite some nice metadata and ensures you can match precisely the list of authors/maintainers between what gets displayed on Zenodo and what the repository copyright shows. In a way it is the opposite view - I use as authors the same list of people as in the copyright. The list of contributors I would hope will tend to be (much) larger - always a great thing! - and we are acknowledging contributors via https://allcontributors.org/ (there's the caveat that the README has to be md and not rst, though). This separation between maintainers and contributors seems fair (as long as all are acknowledged appropriately).