Search code examples
rcranroxygen2

How to acknowledge contributors of ideas (not code) to R package (using roxygen2)?


Someone can help with an R package in a number of ways, including

  1. A substantial body of original code/ideas (author or contributor)
  2. Some trivial code (e.g. fixing a typo) (possibly contributor)
  3. No code, but providing ideas or domain expertise ( ?? )

In the first instance, an author role would be most appropriate. In roxygen2 this could look like so (aut):

Authors@R: c(
    person("Hadley", "Wickham", , "hadley@rstudio.com", c("aut", "cre"), comment = c(ORCID = "0000-0003-4757-117X")),
    person("Romain", "Fran\u00e7ois", role = "aut", comment = c(ORCID = "0000-0002-2444-4226")),
    person("Lionel", "Henry", role = "aut"),
    person("Kirill", "M\u00fcller", role = "aut", comment = c(ORCID = "0000-0002-1416-3412")),
    person("RStudio", role = c("cph", "fnd"))
    )

In the second case, a contributor role may (or may not) be appropriate. e.g.

Authors@R: c(
    person("Some", "One", , "someone@rstudio.com", c("ctb"))

But when someone helps with ideas/discussion/domain expertise, but hasn't contributed code (case 3), is a contributor role still appropriate, and if not, does this change if the ideas shaped the direction of the package - i.e. their ideas were very important despite them not writing the code.

What I know so far

The Library of Congress defines contributor as

A person, family or organization responsible for making contributions to the resource. This includes those whose work has been contributed to a larger work, such as an anthology, serial publication, or other compilation of individual works. If a more specific role is available, prefer that, e.g. editor, compiler, illustrator

Another possibility is conceptor

A person or organization responsible for the original idea on which a work is based, this includes the scientific author of an audio-visual item and the conceptor of an advertisement

But this seems to indicate the whole work/package is based on their idea (which could be true, but not necessarily)

Other references

Hadley defines contributors as

those who have made smaller contributions, like patches.

Question

What is the appropriate role for someone whose only input is ideas (not code), and are there ways other roles for attributing due credit to those who provide important ideas to an R package(e.g. note in README.md, a separate file e.g. CONTRIBUTIONS file in root directory, something else??)


Solution

  • tl;dr I'd choose between aut and ctb depending on the magnitude of the contribution (as @Dason says, ctbs need not have written code). Because you said "their ideas were very important", it sounds like aut would be appropriate.

    LOC references are fine, but direct guidance from R-Core is in ?person and in Kurt Hornik's (an R-core member) R Journal article (these sources have more detail than Writing R Extensions, which just says "See ?person for more information."). From Hornik's article:

    In general, while all MARC relator codes are supported, the following usage is suggested when giving the roles of persons in the context of authoring R packages:

    • "aut" (Author): Full authors who have made substantial contributions to the package and should show up in the package citation.
    • "ctb" (Contributor): Authors who have made smaller contributions (such as code patches etc.) but should not show up in the package citation [emphasis added]

    None of the other roles (com, cph, cre, ctr, dtc, fnd, rev, ths, trl) seem relevant here.

    I don't think there is any other standardized venue for providing contribution info, but you could add information either to the overall package help file aliased to pkgname-package or in the comment field for a package contributor:

    The ‘comment’ field can be used for “arbitrary” additional information about persons.