DOI for each release of our public software

[brechmos-stsci]

There was some discussion on one sprint team about how to reference our software. Obviously DOI has become the standard for referencing journal articles with a link, this seems to be an obvious way to do it for released software as well.

So, for discussion, an opinionated thought is that we should have a Zenodo DOI for each released piece of software and for the GitHub repo as well (which will then point to the latest). This is up for discussion and I think this would be a good place for the discussion.

(I will probably re-write the text in the PR a bit, but wanted to prompt the discussion.)

@hcferguson @arfon @eteq @stscicrawford

[pllim]

1. Blanket DOI vs one separate DOI per release?
2. Is this requirement retroactive? Do we have to go back and DOI all the release we had made like the past 30 years?

[brechmos-stsci]

The thought would be to have one blanket DOI for the repo (this points to the latest release). And then have one for each release.

I don't think it needs to be retroactive :).

[arfon]

Right. And Zenodo supports versioned DOIs now which makes this easier too I think https://blog.zenodo.org/2017/05/30/doi-versioning-launched/

On Mon, Feb 11, 2019 at 1:43 PM -0500, "Craig Jones" notifications@github.com<mailto:notifications@github.com> wrote:

The thought would be to have one blanket DOI for the repo (this points to the latest release). And then have one for each release.

I don't think it needs to be retroactive :).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/spacetelescope/style-guides/pull/83#issuecomment-462444614, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AAARgy_OVR56Lw0CGwevedzY3qzedLy8ks5vMbm0gaJpZM4a0zBK.

[larrybradley]

@pllim Zenodo will always give a new DOI per release -- it's not possible to have only a single "blanket" DOI across different releases. However, you can have a "latest" DOI if you use their "versions" system (e.g. github releases).

[stscicrawford]

For DOI to encompass the software in general, there are the following options:

1. Submit to ASCL
2. Submit to JOSS
3. Submit to an astronomy journal
4. Or do all three!

[pllim]

do all three

Let's not go crazy. I barely have time to document the code itself... Let alone write journals. We're not all astronomers here. 😉

[arfon]

If we're going to ask people to create DOIs for these packages, perhaps we should say something about adding citation guidelines to READMEs and possibly adding a __citation__ method (e.g. https://github.com/adrn/CitationPEP)

[pllim]

Talking about citation, what about https://swcarpentry.github.io/git-novice/12-citation/ ? Or does DOI supersede the need of a CITATION file?

[pllim]

Re: Astropy citation -- While it works, we have run into problems once in a while (especially from people trying to package Astropy in their own distro) with the soft linking of CITATION file at top level. Just know this before you jump into it is all I am saying.

[arfon]

Even if there's a DOI, I think we should have explicit instructions in the README explaining how we want to package to be cited. For example, in Dan FM's corner.py he gives people a bibtex snippet:

@article{corner,
  doi = {10.21105/joss.00024},
  url = {https://doi.org/10.21105/joss.00024},
  year  = {2016},
  month = {jun},
  publisher = {The Open Journal},
  volume = {1},
  number = {2},
  pages = {24},
  author = {Daniel Foreman-Mackey},
  title = {corner.py: Scatterplot matrices in Python},
  journal = {The Journal of Open Source Software}
}

The __citation__ method can simply return something like this ☝️. To generate the appropriate bibtex snipped doi2bib can be used.

For extra points, I think adding a CITATION file is a reasonable idea too. There's even a machine-readable spec for this these days: https://citation-file-format.github.io/

[brechmos-stsci]

@arfon, sorry, are you suggesting a change to this PR, or more documentation somewhere else? (and in particular, @eteq and @stscicrawford is there anything else on this ticket, or is it good to merge?)

[arfon]

Even if there's a DOI, I think we should have explicit instructions in the README explaining how we want to package to be cited. For example, in Dan FM's corner.py he gives people a bibtex snippet:

@brechmos-stsci - yes, I think we should do this ☝️. Basically I think we want to make it as easy as possible for people to cite us :-)

[stscicrawford]

For the sake of keeping PR's focused on a single issue, I think this can be merged as is once a new issue about citation is created. It probably should be a separate PR, but we do need it. @brechmos-stsci can you take the lead on that?