Chapter 9 Collaboration Guide

Having contributors will improve your package, and if you onboard some of them as package authors with write permissions to the repo, your package will be more sustainably developed.

This chapter contains our guidance for collaboration, in a section about making your repo contribution- and collaboration-friendly by infrastructure (code of conduct, contribution guidelines, issue labels); and a section about how to collaborate with new contributors, in particular in the context of the rOpenSci’s “ropensci” GitHub organization.

9.1 Make your repo contribution and collaboration friendly

9.1.1 Code of conduct

We require that you use a code of conduct such as the Contributor Covenant in developing your package. You can document your code of conduct in a CODE_OF_CONDUCT.md or CONDUCT.md file in the package root directory, and link to this file from the README.md file. usethis::use_code_of_conduct() will add the Contributor Covenant template to your package.

9.1.2 Contributing guide

We have templates for issue, pull request and contributing guidelines that you can find in this GitHub repository along with some instructions to insert them into your repository.

You can tweak them a bit depending on your workflow and package. For example, make sure contributors have instructions in CONTRIBUTING.md for running local tests if not trivial. CONTRIBUTING.md can also contain some details about how you acknowledge contributions (see this section) and the roadmap of your package (cf this example).

9.1.3 Issue labelling

You can use labels such as “help wanted” and “good first issue” to help potential collaborators, including newbies, find your repo. Cf GitHub article. You can also use the “Beginner” label. See examples of beginner issues over all ropensci repos.

9.2 Working with collaborators

9.2.1 Onboarding collaborators

There’s no general rOpenSci rule as to how you should onboard collaborators. You should increase their rights to the repo as you gain trust, and you should definitely acknowledge contributions (see this section).

You can ask a new collaborator to make PRs (see following section for assessing a PR locally, i.e. beyond CI checks) to dev/master and assess them before merging, and after a while let them push to master, although you might want to keep a system of PR reviews… even for yourself once you have team mates!

A possible model for onboarding collaborators is provided by Jim Hester in his lintr repo.

If your problem is recruiting collaborators, you can post an open call like Jim Hester’s on Twitter, GitHub, and as an rOpenSci package author, you can ask for help in rOpenSci slack and ask rOpenSci team for ideas for recruiting new collaborators.

9.2.2 Working with collaborators (including yourself)

You could implement the “gitflow” philosophy as explained by Amanda Dobbyn in this blog post.

One particular aspect of working with collaborators is reviewing pull requests. Even if not adopting gitflow it might make sense for repo collaborators to make PRs and have them reviewed, and in general PRs by external developers will need to be assessed Sometimes you’ll be fine just reading the changes and trusting Continuous integration. Sometimes you’ll need more exploration and even extension of the PR in which case we recommend reading “Explore and extend a pull request” in happygitwithr.com.

9.2.3 Be generous with attributions

If someone contributes to your repository consider adding them in DESCRIPTION, as contributor (“ctb”) for small contributions, author (“aut”) for bigger contributions. Also consider adding their name near the feature/bug fix line in NEWS.md We recommend your being generous with such acknowledgements.

As a reminder from our packaging guidelines if your package was reviewed and you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the Authors@R field with a Reviewer contributor type ("rev"), like so:

    person("Bea", "Hernández", role = "rev",
    comment = "Bea reviewed the package for ropensci, see <https://github.com/ropensci/onboarding/issues/116>"),

Only include reviewers after asking for their consent. Read more in this blog post “Thanking Your Reviewers: Gratitude through Semantic Metadata”. Note that ‘rev’ will raise a CRAN NOTE unless the package is built using R v3.5. As of June 2018 you need to use roxygen2 dev version for the list of authors in the package-level documentation to be compiled properly with the “rev” role (because this is a MARC role not included yet in royxgen2 CRAN version from February 2017).

Please do not list editors as contributors. Your participation in and contribution to rOpenSci is thanks enough!

9.2.4 Welcoming collaborators to rOpenSci

If you give someone write permissions to the repository, please contact one of the editors or Stefanie Butland so that this new contributor might

  • get invited to rOpenSci’s “ropensci” GitHub organization (instead of being outside collaborators)

  • get invited to rOpenSci Slack workspace.