How to cite the package?

[eduardo-rodrigues]

Hi, I was checking for a Zenodo label in the README and found none. I was then going to suggest to get Zenodo to mint DOIs so that the package can be cited - please check and follow our org guidelines ;-) - and looked online to find out that you do connect to repo to Zenodo, see https://zenodo.org/record/5078496#.YmAX5YtByUk. Better get the procedure automated and update the README.

[jpivarski]

I like the method of adding a CITATION.cff file, since it lets you curate the list of authors and provide full names for people who might have only a GitHub userid. I've done that for Awkward but still need to do it for Uproot.

As a bonus, you get a "Cite this repository" link in a standard place on the GitHub right-bar, which provides pre-rendered and BibTeX without clicking through to Zenodo, which is also beneficial because I like to insist on using the DOI that points to the latest version, whatever that is, rather than the individual DOIs for each released version that Zenodo highlights. There are arguments for both (one uses a particular version of software in a particular analysis), but I prefer the version-independent DOI because then all references to "the idea of" the software library are the same and can be counted as a group.

[eduardo-rodrigues]

Thanks for letting us know about that .cff file. I was not aware of it myself, for example.

I'm using .zenodo.json files in a couple of repositories, BTW, to curate the list of authors that get displayed on Zenodo. That is very handy. Got the idea from @matthewfeickert's file for pyhf.

I also prefer the version-independent Zenodo DOI and that's the one I always link to in the READMEs of my repositories. Up to users to go and find a specific DOI if they so wish. That's easy once one clicks on the version-independent Zenodo DOI badges we provide in the READMEs.

[matthewfeickert]

I would second the idea of a CITATION.cff. Zenodo also supports it and so will generate metadata from it as well and as CITATION.cff is a standard you can convert it to multiple citation formats easily.

We've used it in pyhf since https://github.com/scikit-hep/pyhf/pull/1551 but we still have a .zenodo.json file as (at the time of pyhf's last release) there were a few areas in which Zenodo hadn't made the CITATION.cff perfect. But I think in general it is a good format to standardize around. I would recommend also having in the docs or README how you want people to cite you though in BibTeX format.

[mattleblanc]

Hi! I would like to cite this package soon. Could you let me know of the preferred citation format? It looks like zenodo isn't kept up-to-date with the releases here on github.

[matthewfeickert]

Hi! I would like to cite this package soon. Could you let me know of the preferred citation format? It looks like zenodo isn't kept up-to-date with the releases here on github.

@lovaslin Can you make sure that Zenodo is synced with GitHub?

@mattleblanc I'll let @lovaslin get back to you on exact citation information, but if you're using the latest tag from GitHub (v0.4.0) I would suspect that the BibTeX would look something like

@software{pyBumpHunter,
  author = {Louis Vaslin},
  title = "{pyBumpHunter: v0.4.0}",
  version = {0.4.0},
  doi = {10.5281/zenodo.5069641},
  url = {https://doi.org/10.5281/zenodo.5069641},
  note = {https://github.com/scikit-hep/pyBumpHunter/releases/tag/v0.4.0}
}

where https://doi.org/10.5281/zenodo.5069641 is the entry for all versions.

[lovaslin]

Hello @mattleblanc,

The citation proposed by @matthewfeickert is probably the best option. You could also cite this paper that presents the features of the package. I will work on adding proper citation information on GitHub soon.

[mattleblanc]

Thanks a lot for the quick reply! I didn't know about that paper -- I'm happy to cite it.

Just to confirm, should the author of the software repo citation just be @lovaslin?

[eduardo-rodrigues]

Hello. note that the Zenodo link that @matthewfeickert gave is the one for the PyHEP workshop presentation, not the repository itself.

@lovaslin, it only takes a few minutes to link Zenodo to the repo and make a trivial "patch" release so as to get a badge to be cited. Can you do that asap? It's so rare that users ask for a way to cite that I feel we ought to act quicky :-). Thumbs up to you @mattleblanc.

[eduardo-rodrigues]

BTW @mattleblanc, kindly post here once you cite us, or directly in https://github.com/scikit-hep/scikit-hep.github.io as we have the page https://scikit-hep.org/projusers/publications to record "customers". That's very much appreciated.

[eduardo-rodrigues]

@lovaslin, if you copy https://github.com/scikit-hep/particle/blob/master/CITATION.cff and make the obvious changes you can quickly get yourself a "cite us" on the repo as Jim points out above :-).

[eduardo-rodrigues]

Anyway, we have enough material here. Any one of us in fact can make the connection to Zenodo, I believe, so let's see where we are on Monday ...

[matthewfeickert]

Hello. note that the Zenodo link that @matthewfeickert gave is the one for the PyHEP workshop presentation, not the repository itself.

Ah, you're right! I missed that the Zenodo file that you linked in the first post was for the workshop — sorry, sloppy on my side. Yes, as there is no(?) Zenodo DOI for the project it would be great to fix this soon.

Thumbs up to you @mattleblanc.

:clap:

[mattleblanc]

BTW @mattleblanc, kindly post here once you cite us, or directly in https://github.com/scikit-hep/scikit-hep.github.io as we have the page https://scikit-hep.org/projusers/publications to record "customers". That's very much appreciated.

I will certainly try to do that! The result will not be public for a little while, though, so feel free to ping me around the start of June if I haven't come back by then.

[eduardo-rodrigues]

@lovaslin, it only takes a few minutes to link Zenodo to the repo and make a trivial "patch" release so as to get a badge to be cited. Can you do that asap? It's so rare that users ask for a way to cite that I feel we ought to act quicky :-).

Hi again @lovaslin, will you make the link to Zenodo or shall I just go ahead myself? It simply requires a log-in to Zenodo and 2 clicks ... It's a 1-minute job ... Then we make a trivial release and we're done here. Please let us know asap.

[lovaslin]

Hello,

I just fliped the switch on Zenodo. Now I need to make a release to get a doi. Can I just go ahead and do it directly from master ? I don't plan to do any other changes compare to the current stable release.

[eduardo-rodrigues]

Yep. As soon as you tag you will get an upload to Zenodo. Then you can copy the badge and provide it in the README. Don't forget to use the "all versions" DOI on the README, which is standard. Anyone can use a DOI for a specific version if they so wish by checking the actual version on Zenodo. My 2 cents.

[eduardo-rodrigues]

Hello @lovaslin, do you need any help to add the badge, add a .cff file and finalise this?

[lovaslin]

Hello, I added the badge and CITATION.cff file. For now, I put only my name in the file. I can add names of other main contributors.

I think this should fix the issue of how to cite the package.

[eduardo-rodrigues]

Hi. Cool. Though you should rather use the "all versions" Zenodo version, see 10.5281/zenodo.7684558.

And for the .cff file I think it is better not to add a release date to "paint itself in a corner", see the various examples in org packages ...

Then I reckon also you're good to close this task.

[eduardo-rodrigues]

I created https://github.com/scikit-hep/pyBumpHunter/pull/16 to have the more standard DOI badge. Kindly review and merge, @lovaslin.

[eduardo-rodrigues]

... and https://github.com/scikit-hep/pyBumpHunter/pull/17 for an improvement to the CITATION.cff file. Feel free to close once the 2 MRs are dealt with.

[eduardo-rodrigues]

Closed via https://github.com/scikit-hep/pyBumpHunter/pull/16 and https://github.com/scikit-hep/pyBumpHunter/pull/17.