10 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. It can also be very enjoyable to work as a team!

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.

Besides these mostly technical tips, it is important to remember to be kind, and to take others’ perspective into account especially when their priorities differ from yours.

10.1 Make your repo contribution and collaboration friendly

10.1.1 Code of conduct

After transfer to our GitHub organization, rOpenSci Code of Conduct will apply to your project. Please add this text to the README

Please note that this package is released with a [Contributor
Code of Conduct](https://ropensci.org/code-of-conduct/). 
By
contributing to this project, you agree to abide by its terms.

And delete the package current code of conduct if there was one.

10.1.2 Contributing guide

You can use issue, pull request and contributing guidelines. Having a contributing file as .github/CONTRIBUTING.md or docs/CONTRIBUTING.md is compulsory.

Example of useful content:

  • Style preferences? You might however prefer to make style a configuration (of lintr, styler) or to fix code style yourself especially if you don’t use a popular code style like the tidyverse coding style.

  • Infrastructure like roxygen2?

  • Process preferences? Issue before a PR?

  • Scope? E.g. in skimr.

  • Sandbox account creation? Mocking in tests? Use links to external docs.

Example: contributing guide template by Peter Desmet.

Adding a personal touch to your contributing guide might make it look less generic and therefore more sincere.

CONTRIBUTING.md can also contain some details about how you acknowledge contributions (see this section) and the roadmap of your package (cf this example).

We encourage you to direct feedback that is not a bug report or a feature request to rOpenSci forum, after making sure you’d see such questions on the forum. Users can use the forum to ask questions about use and report their use cases, and you can subscribe to individual categories and tags to receive notifications about your package. Feel free to mention this in the docs of your package and/or the contributing guidelines/issue template. Please direct your users to tag posts with the package name.

Once a pull request is closer to being merged, you could use a GitHub Actions PR workflow to style the code with styler.

10.1.3 Issue management

By using GitHub features around issues you can help potential contributors find them, and make your roadmap public.

10.1.3.1 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.

10.1.3.2 Pinning issues

You can pin up to 3 issues by repository that will then appear at the top of your issue tracker as nice issue cards. It can help advertise what your priorities are.

10.1.3.3 Milestones

You can create milestones and assign issues to them, which help see what you plan for the next version of your package for instance.

10.2 Working with collaborators

First thing first: keep in touch with your GitHub repository!

  • do not forget to watch your GitHub repository to be notified of issues or pull requests (alternatively, if you work in bursts, maybe add the information to the contributing guide).

  • do not forget to push updates you have locally.

  • disable failing tests if you cannot fix them as they create noise in PRs that can puzzle new contributors.

10.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.

10.2.2 Working with collaborators (including yourself)

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

  • Keep the default branch (main or master) as shippable as much as possible

  • Branches are cheap. Use them extensively when developing features, testing out new ideas, fixing problems.

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.

10.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. Traditionally when citing a package in a scientific publication only “aut” authors are listed, not “ctb” contributors; and on pkgdown websites only “aut” names are listed on the homepage, all authors being listed on the authors/ page.

At a minimum consider adding the name of contributors near the feature/bug fix line in NEWS.md.

We recommend your being generous with such acknowledgements, because it is a nice thing to do and because it will make folks more likely to contribute again to your package or other repos of the organization.

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 [email protected] field with a Reviewer contributor type ("rev"), like so:

    person("Bea", "Hernández", role = "rev",
    comment = "Bea reviewed the package (v. X.X.XX) for rOpenSci, see <https://github.com/ropensci/software-review/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. Make sure you use roxygen2’s latest CRAN version.

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

10.2.4 Welcoming collaborators to rOpenSci

If you give someone write permissions to the repository,

  • please contact one of the editors so that this new contributor might get invited to rOpenSci’s “ropensci” GitHub organization (instead of being outside collaborators)

  • please contact rOpenSci community manager Stefanie Butland so that this new contributor might get get invited to rOpenSci Slack workspace.

10.3 Further resources