Should the rOpenSci Dev Guide include package citation best practices?

General Q&A
, ,
1

In a recent submission in our software review system a user asked if rOpenSci has policies/guidance regarding package citations https://github.com/ropensci/software-review/issues/266#issuecomment-454489115

We don’t at this time.

Should we have policies or best practice guidelines about package citations in our dev guide?

If no, why?

If yes, what should the best practices be?

3 Likes
2

YES. Generally, we should adhere to FORCE11 Guidelines: https://www.force11.org/software-citation-principles.

  • We should require CITATION files and provide recommended formats.
  • We should require/autogenerate codemeta.json files.
  • We should highly recommend a “Citing this package/data” section in README
4 Likes
3
  • If we require citation files, do we require it before we review a package, or just saw to add one after review?
  • For codemeta, do we require it before review? I’ve been asking people to add them after acceptance thus far.
  • i’ve heard of force11, but how do we implement them in practice? what do we actually tell people to do to follow it?
4

CITATION and codemeta should be:

  • In the packaging guide, so checked by reviewers
  • Part of automatic package checks
  • On editor’s radar so if the above don’t work, they are flagged. I think doing this at end of review is fine, as the contents of these files would likely change over the course of review.

We’re covering a lot of FORCE11 principles in general. Some that we could do more on are:

  • Making sure citations cite a version of the package - CITATION/codemeta/README files should include versions, as should our review badges.
  • Including author identifiers - promoting use of author ORCiDs more. Author roles are in good shape.
  • Archiving - eventually making sure all RO packages go to a scientific repository, not just JOSS packages.
5

Thanks.

@cboettig any thoughts on this?

6

Revisiting this thread to find what needs to be added to the dev_guide/tooling.

At the moment we recommend the creation of codemeta.json. ORCIDs are mentioned in the authorship section.

I guess the metadata section should

  • also recommend the creation of a CITATION file. usethis::use_citation() helper isn’t enough. Should we work on a helper function in rodev? Any good models of CITATION files?
  • how does one keep CITATION up-to-date? We could add it to our guidance about releases, other ideas?
  • the explanation of DOIs/archiving should ideally come before recommending CITATION files but the section about package metadata comes quite early in the packaging guide. Would a sentence or two in that section be enough? Any particular recommendation for these two sentences @noamross?

We don’t have a new tool for automatic checks at the moment so checking codemeta.json and CITATION are present and correct so I’ve only filed an issue so we don’t forget.

1 Like
7

yes

good question, i think maybe you can include executable code in a citaiton file to make sure a date is correct, etc., or no?

8

Any good examples of CITATION for me to use in rodev?

Depending on how fast I am, this might go into the autum release of the dev guide instead of this next release.

9

do you mean a citation for rodev itself?

10

No, examples of good citation files of packages so that I might know what a function for creating one automatically should do :slightly_smiling_face:

11

i think @cboettig should know best here, but i think he’s on vacation right now :clock1:

1 Like
12

Date and pkg release can be automated in CITATION file. I’ve done this as well as included the JOSS paper citation in my packages.

See nasapower, https://github.com/ropensci/nasapower/blob/39c9fcfd8c8b8be8c6c894e1e301989eb61e3d39/inst/CITATION

1 Like
13

Nice, thanks for the example!

14

@adamhsparks example looks great! Though I think ideally the second bibentry (Manual, for the package itself) would also have the version and possibly the Zenodo DOI). Still Adam’s example is notably better than any of mine, including codemetar which you might think would at least have a CITATION file and a JOSS badge…

15

@cboettig, the second, Manual, bib entry and text version do have the version number, see the note field. However, as you noted, it is lacking the DOI. I could however point to the base DOI that Zenodo hands out.

1 Like
16

We should highly recommend a “Citing this package/data” section in README

Is this needed given that in pkgdown websites, the CITATION file presence triggers the creation of a citation section in the sidebar? See for instance pkgdown template and utilities for rOpenSci docs • rotemplate

17

Personally, I take a “belt-and-suspenders” approach and still put citation things in the README. The GH repo, rather than the docs page, is still often the main landing page that people read before downloading and using a package. (I have no data on this, it’s true for me ¯_(ツ)_/¯ )

3 Likes
18

I do this too, just to make it painfully obvious how to cite the work.

2 Likes