Add CITATION.cff

[agoose77]

Description of new feature

GitHub has just added support for CITATION.cfffiles

I assume that we might already have a citation in mind, so I thought I'd bring it to our collective attention.

[jpivarski]

In fact, I have a browser tab open to https://citation-file-format.github.io/ The citation is in the Zenodo badge. A CITATION.cff file would bring more attention to it.

[agoose77]

Thanks for the reminder, it didn't occur to me to check the badges for a DOI. It looks like we'd be duplicating some of our auto-generated content like contributor information etc. I wonder if there is an easy tool to integrate that, or whether we need to add something to the release process to generate a new CITATION.cff.

[jpivarski]

Looking at the structure of a CITATION.cff, I think it could be hand-written. The DOI doesn't change: I have the badge linked to the versionless DOI, which always points to the latest version. I think it's actually a problem that Zenodo defines the authors to be the set of contributors to the repository, in part because some people contribute a lot more than others (the variance is huge), but also because some people contributed to scikit-hep/awkward-0.x and not scikit-hep/awkward-1.0 (different repos). The contributors to scikit-hep/awkward-0.x are in the allcontributors list because I put them in there manually.

But if we want a shorter list for CITATION.cff, where do we draw the cut-off? I suppose this is why you were considering auto-generating the CITATION.cff, to include new authors as they appear, though the cut-off of people who made substantial contributions would be difficult to automate (number of lines changes?). Also, even though a lot of people made significant contributions, adding a big block of names in the references section of a paper only increases page count, and some journals include the references section in the page count that limits the lengths of articles.

For these practical reasons, perhaps it should be just "Jim Pivarski et al"? (With a strong emphasis on the "et al".) This way, it doesn't get too big in references sections and the link back here has pictures of everybody who contributed—something people find if they click through the link, which is to say, if they're interested. For years, ROOT was cited with just two names (Rene and Fons), although the Zenodo link has 30 names (still much less than the number of people who have contributed to ROOT, 282). I think those 30 names are people who are now or have been on the ROOT Team page, but Awkward Array doesn't have a well-defined team.

Actually, let me put a bit more thought into this. Some people have been funded to work on Awkward Array. They are:

• @jpivarski / Jim Pivarski, Princeton
• @ianna / Ianna Osborne, Princeton
• @henryiii / Henry Schreiner, Princeton
• @ioanaif / Ioana Ifrim, Princeton
• @trickarcher / Anish Biswas, Manipal Institute of Technology (as GSoC and IRIS-HEP Fellow)
• @reikdas / Pratyush Das,, Institute Of Engineering and Management, Kolkata (at that time, now Purdue, as an IRIS-HEP Fellow)
• @EscottC / Charles Escott, Sacred Heart University (at that time, now Columbia, as a GSoC student)
• @Jayd-1234 / Jaydeep Nandi, National Institute of Technology, Silchar (as a GSoC student, though his involvement was at the very beginning of when it was called "Awkward Array")

But using that to define the list wouldn't count people who made substantial contributions, like @nsmith-, @drahnreb, @veprbl, @chrisburr, and you.

Now that you're all linked into this thread, maybe you have opinions/preferences? Am I worrying too much about making the reference a big block of names by including everybody? (27 people in .all-contributorsrc, which is less than ROOT's curated list of 30 names.)

[agoose77]

My personal take is favouring simplicity over adding infrastructure to keep track of a citation file, but I'm perhaps a bit blasé when it comes to the premise in the first place. So, at least for my name, +0 on including in a CITATION.cff file, and +1 on keeping it simple with Jim Pivarski et al.

[ianna]

+1 on keeping it simple with Jim Pivarski et al.

+1

[henryiii]

One irritating thing is it seems the CITATION file has the version number in it - having another place (sometimes the only place) to change a version number is really a step backward for some projects. "Last GitHub release" would be really nice instead. :)

For names, I tend to prefer keeping a full author list then using a rule to truncate all of them (X names et. al. after a limit of Y names), but for software, this likely is hard to keep up (if all-contributors adds support, that might be really nice). Maybe the top X(=3?) contributors on GitHub (they are sorted in the GH UI), or anyone who has contributed more than X% (%10?) of the code, etc. I think the rule proposed above could be "list of people who have creative control over the software, et al". I'm mostly looking for a way to make this a suggestion that can apply to other projects. Some projects have more than one core developer; boost-histogram would likely need to be @HDembinski and me at the least. It would be nice to adopt a community guideline. (@danielskatz might have suggestions or input here?) - I'd be happy to propose a page to scikit-hep.org/developer .

[danielskatz]

It would be more effective to open an issue in https://github.com/citation-file-format/citation-file-format for feature requests or format changes than to just comment about them here :)

[danielskatz]

perhaps a feature request to all-contributors too?

[danielskatz]

For Parsl, we decided that all repo contributors with non-trivial/typo changes would be added as authors, in addition to other non-repo contributors

[henryiii]

It would be more effective to open an issue

I haven't even set this up in a single repo yet, so probably not quite ready for that, but yes, I will if it's a problem. I first might just see what it does if you leave that blank, for example.

[matthewfeickert]

👋 Joining this Issue's discussion given thoughts / rough edges in scikit-hep/pyhf#1541. I think one of the problems is that GitHub isn't being very clear on what parts of the CFF spec they support, as it clearly isn't all of it, but only GitHub can answer that so we'll need to open an Issue.

[matthewfeickert]

During the release of pyhf v0.6.3 we noticed some unexpected issues with CITATION.cff that we didn't have with .zenodo.json (c.f. scikit-hep/pyhf#1541 (comment)).

[agoose77]

Closed by #1257