How precise should citations of the code be?

[illorenzo7]

Nick's latest pull request #341 made me think (again) about the citation standard for Rayleigh now that it has a stable release. There are three sub-issues in my mind:

A. Most (probably all) future publications will not actually be using v 1.0.0. That's because more pull requests will likely be merged soon, so unless everyone is super careful to run all production-level simulations directly from the v 1.0.0 executable, they will be using different versions. I think it would be good to instruct people to also include the shortened git hash (possibly with a hyper-link to the commit) in the actual paper citation if possible. I am imagining the citation would have two links: one to the DOI (v 1.0.0 or the latest stable release on Zenodo) and one to the specific git hash after v 1.0.0. Or, if the journal doesn't allow links people can still find the precise version of the code someone used. This would make all work fully reproducible. Is that possible and/or practical? @gassmoeller maybe you have some insight from aspect? (It might also be good to encourage people to use the same git hash for all simulations in a suite that's going to be published---I know I am guilty of continually doing fresh pulls and thus mixing and matching versions within a suite).

B. If people use their own branch, can we encourage them to make their Rayleigh fork publicly available---and then list the six-digit hash (hyperlinked to the citation) as above? Then the citation's DOI would still --> Zenodo stable release, but the hash (mentioned in part A) would point to their personal repository.

C. This is more of a practical issue, but I've recently noticed that Zenodo has a universal DOI for different versions of a project. Each new version will get its own DOI (v 1.0.0 = 10.5281/zenodo.5683601) but the latest version will always be this universal DOI (in this case 10.5281/zenodo.1158289). Should we encourage people to use the universal DOI in their citations? Otherwise we may have to update the citation instructions every time a new version is released.

[feathern]

I agree that we should talk about this sometime in the next couple of months. I see what you mean.

[orvedahl]

This was discussed a bit during the CIG staff meeting earlier today. There are two categories of users: a) made modifications to the code and b) used the public code with no modifications. This leads to three cases when it comes to citations:

1. you pull down the v 1.0.0 release (or any release that has a zenodo DOI) and use it without any modifications --- simply cite the zenodo release.

2. you pull down the v 1.0.0. release, then some time later do a "git pull" to use the latest updates, but still have not made any modifications --- cite the zenodo release as well as the git hash that you used.

3. you are using some kind of custom version of Rayleigh, i.e., your own fork, or the main release with your own modifications. You should obtain a zenodo citation for that version, and then cite the main Rayleigh code as well as your particular version. Lorraine will be working on some guidelines and/or instructions for this that will appear on the new geodynamics website.

[feathern]

This is why we probably need a short JOSS paper. Ideally, there would be a common reference that's cited, as well as a version reference.

[illorenzo7]

@feathern Not closing this yet, as I think some of the same issues remain currently. In particular the documentation is pretty descriptive, but there is still some ambiguity in how specific to be when citing the proper version, what to do if versions are mixed and matched within a simulation suite, whether to use Universal DOI, etc.

I also think it would be good to add preferences for how users cite Rayleigh in their presentations, posters, and/or press-releases.