JOSS review - CITATION.cff

[pabloitu]

This issue tracks a comment by @sscivier from the JOSS review thread.

Source (JOSS): openjournals/joss-reviews#9408 (comment)

I would encourage the authors to add a CITATION.cff file to the repo. This would:

* Make it easy for users to cite their use of the software, with a "_Cite this repository_" button automatically added to the repository side bar on GitHub.

* Formalise and make the metadata machine-readable.

* Allow users to cite the JOSS paper and the software itself with its Zenodo DOI. Within the `CITATION.cff` file, the authors may specify a `preferred-citation` that could point to the JOSS paper.

* Allow for e.g., ORCiDs to be properly linked, and ensure all authors are credited appropriately.

* Enable version specific citations consistent with Zenodo.

In line with this, I would encourage the authors to add a "How to cite" (or similar) section to the README.md.

[pabloitu]

Thank you for this info! I added a CITATION.cff and included the into in the README.md, now linking to the zenodo repo, but hopefully to the JOSS paper once its published. Changes added in #110

[sscivier]

Great! Thanks, @pabloitu.

[sscivier]

Just double-checked this and there seems to be a difference in the number of authors included in the CITATION.cff file, and listed in the How to Cite section in the README.md. I understand there are more authors on the paper than made contributions to the code. I also understand this will all get updated once the paper is published. For now, my opinion would be to leave it up to you whether the full paper author list is used for the software citation--I don't have a strong view either way (perhaps @andreww would have some insight on this?). However, I would recommend ensuring consistency between the details appearing in the README.md and the CITATION.cff file. In the How to Cite section in the README.md, I would then suggest either pointing to the "Cite this repository" button, or having a copy of the bibtex citation that is generated by the "Cite this repository" button.

[andreww]

My view is that it's up to the authors to point users to what they think is the best citation for their software. Having said that, having something to cite is one of the reasons JOSS exists.

I would certainly make sure people looking to cite floatCSEP get a consistent message from the README and cff files. Part of the process after review is for me to check all the versions and links tie together properly but JOSS doesn't mint a doi you can cite until we actually publish the paper. The thing I think most people do is put something reasonable (e.g. a zenodo archive) in the citation links and then, if they want the JOSS paper to be the thing people should cite, update the github repository to point to that once the JOSS paper is out.

[pabloitu]

I've made the CITATION.cff consistent with the latest Zenodo release's metadata (only 4 authors present at the moment in which the software was created 3 years ago). I'm happy to update the CITATION.cff so it points its "Preferred citation" to the JOSS article once it can be published.

Additionally, I've updated the README.md instructing to use the "Cite this repository" button, but also placed a consistent citation text beneath.

• Note: If the Zenodo version doesn't make sense to you, it is because the zenodo-github webhook delivery broke after v0.3.0, and after some research and unfruitful debugging, it is likely due to not having a CITATION.cff in the repo. Thus I find myself in a small circular conundrum together with this raised issue, but I hope you agree with the solution proposed above.

[sscivier]

Thanks, @andreww and @pabloitu. That's all fine with me.