Skip to main content

rOpenSci Community Contributing Guide

3 rOpenSci Resources

Each section of this chapter describes and links to a specific rOpenSci resource with a “How to contribute” list of actions you could take.

Not sure where to get started? Browse What brings you here? to help you explore what you want to get out of contributing. Categories - Discover, Connect, Learn, Build, Help - each have “I want to” statements followed by examples of specific ways you can contribute. Each example links to a resource in this chapter to help you take action.

3.1 Code of Conduct

All participation in rOpenSci activities is supported by a Code of Conduct that has clear guidelines for reporting and is enforced by a committee including rOpenSci staff and an independent community member.

3.1.1 How to contribute?

3.2 Communication channels

The Humans of rOpenSci connect and contribute online across many timezones. We carry out our work using multiple channels for one-way and multi-way communications that involve different levels of commitment.

GitHub is the platform we use to host our software and documentation projects using Git version control. Our newsletter, delivered every two weeks, is the ideal way to stay informed without being overwhelmed by communication channels. We use our public discussion forum, Twitter, and Slack, each for specific modes of making announcements, promoting contributions from community members, asking and answering questions about rOpenSci packages and recommended best practices, knowledge-sharing and exploration of ideas, as well as more passive learning by “listening” to community wisdom.

The following table lists every communication channel and its purpose. Below that we describe how we use a few specific channels and provide some advice on deciding whether a question you might have is one for rOpenSci or belongs in a more general forum.

Channel Purpose
Website https://ropensci.org/ https://github.com/ropensci/roweb2 Home of rOpenSci
Newsletter A digest of R package news, use cases, blog posts, events, curated every two weeks. Subscribe via RSS (XML), JSON feed, or email.
Videos Videos from past Community Calls on Vimeo
Twitter - rOpenSci Tweets about rOpenSci software, use cases, blog posts, tech notes, events
Twitter - roknowtifier Bot that tweets new rOpenSci packages or new versions of packages
Video conferencing Community Calls and remote co-working sessions on Zoom
GitHub - ropensci Mature R packages contributed by rOpenSci staff or community-contributed peer-reviewed packages; software peer review system; rOpenSci website
GitHub - ropenscilabs Experimental packages and code experiments from staff, collaborators, and participants of unconfs and related events
GitHub - ropensci-org Non-code repositories like this guide, the blog guide, ideas for Community Calls
Discussion forum Public forum on Discourse for use cases, Q & A about rOpenSci packages, exploration of ideas and best practices
Slack A semi-open space for communications among people who contribute to rOpenSci
Email: info at ropensci dot org To reach rOpenSci staff when other modes are not suitable

GitHub

The majority of rOpenSci’s work happens on GitHub. In this Guide we use terms like “opening an issue” to refer to tracking ideas, enhancements, tasks, or bugs in a project, and “making a pull request” to submit your proposed fix or new feature. If you’d like some general information on the language and workflow of GitHub, see Collaborating with issues and pull requests. To learn about Markdown formatting for interacting with others in issues and pull requests see Getting started with writing and formatting on GitHub. For guidance on connecting R to GitHub we recommend Happy Git and GitHub for the useR - https://happygitwithr.com/.

Public discussion forum

The forum is where we encourage people to have Q & A on a wide range of topics. It is organized in categories including Use Cases where people post examples of how they’ve used rOpenSci packages, Blog where an entry is made every time a new post or tech note appears on our blog, Statistical Software Peer Review for discussion related to developing a software peer review system for statistical software in R, Antarctic for discussions about R in Antarctic and Southern Ocean science. It includes posts like “How do you hire data people in a fair and unbiased way?” in the Community category, to specific help requests about our packages like “Taxize: Get rank of lowest common taxon”.

The benefit of posting to our forum, rather than our semi-open Slack space or by email, is that it is open for others to benefit, searchable within the forum, and discoverable by browser-based searches. Posting in the forum requires login and we encourage people to use their real names.

Slack

We use Slack as a semi-open space for communications among people who have made specific contributions to rOpenSci. These include people who:

People join Slack by invitation from our Community Manager or other staff. If you are eligible, you may contact us via our contact form; provide your full name and email address.

The benefit of Slack is the ability to more directly access rOpenSci staff and community members, including some more experienced folks in channels like #software-review or #package-maintenance, or to watch for postings in #jobs. People consider it an easier place to ask questions or explore ideas because while it has over 500 members, it’s not fully “in the open”. We actively welcome new members and ensure that all conversations are collegial.

How to get help

There is an etiquette to getting help and asking questions. We focus on using, developing, documenting code and infrastructure, and building community, as they specifically align with our mission.

People looking for more general R learning may refer to RStudio Education and The Carpentries.

Read these posts if you have an R question: Where to get help with your R question?, by Maëlle Salmon; Getting help in R: do as I say, not as I’ve done, by Samantha Tyner.

If you’re asking for R help, reporting a bug, or requesting a new feature, you’re more likely to succeed if you include a good reproducible example, a “reprex”. There’s a well-documented package for that including a video, and an rOpenSci Community Call - How to Ask Questions so they get Answered! Possibly by Yourself!, with Jenny Bryan, JD Long, and Scott Chamberlain.

3.2.1 How to contribute?

3.3 Community Calls

Our Community Calls are an ideal way to get familiar with rOpenSci. They give you a feeling for how we blend rigorous expertise and recommendations with a friendly and safe way for all participants - presenters and attendees - to stretch themselves. They’re free and open for anyone to attend, and provide an opportunity to connect with rOpenSci community members around the world. Our session on Maintaining an R package had 90 participants from 18 countries!

We’ve run more than 25 Community Calls since their start in 2015. Topics range widely and include Reproducible research with R, Testing, Security for R, How do you review code that accompanies a research project or paper?, Involving multilingual communities, Research applications of rOpenSci taxonomy and biodiversity tools, Governance strategies for open source research software projects and more!

There’s nothing like hearing a lively technical banter of experts to pick up the vernacular that one can easily build upon. The first-hand tips and tricks, do’s and don’ts, personal anecdotes of what worked beautifully and what crashed terribly, offered by years of experience are yet unmatched in bringing newbies into speaking the community’s language.
Janani Ravi in “Maintaining an R Package - Community Call Summary”

These are not your usual webinar. Some calls might involve two to three speakers on a topic, some give an introduction to our tools in a specific research domain followed by several people presenting their use cases for those tools, and some are a moderated discussion among experts. We always leave at least 20 minutes for Q&A. We use collaborative note-taking allowing participants to share their own ideas or resources and to ask and answer questions.

This live shared document helps everyone … formulate what they would like to say. It also gives people the option to participate without having to … speak up on the call (thus reducing the barrier for people, especially newcomers, to ask questions). The document also gives an opportunity for anyone in the community to share their expertise …
Janani Ravi in “Maintaining an R Package - Community Call Summary”

Recordings of all past calls are available online, with closed captions (transcript of dialogue visible in text on video) for all calls in 2020 or later.

Examples of community call thumbnails from our Vimeo page

3.3.1 How to contribute?

  • Attend a Community Call. No registration required. Find information about our next Call.
  • Watch recordings and read collaborative notes from past Community Calls.
  • Have an idea for a Community Call topic or a speaker to recommend? Have a relevant topic you’re keen to speak about? Recommend topics or speakers for Community Calls. Tell us in our public ideas repository.
  • Are you really interested in the topic of an upcoming call? Why not help organize it? Contact our Community Manager Stefanie Butland, via Slack or our contact form.
  • Are you enthusiastic about the topic and planning to attend? You might want to write a summary for our blog. Contact our Community Manager Stefanie Butland, via Slack or our contact form.

3.4 Blog

The rOpenSci blog contains both long form blog posts and shorter tech notes. It’s a large, rich resource for learning about the R packages developed by staff and by community members and how people use them, the people and processes involved in our open software peer review system, and the value people get from being part of our community. We’ve published more than 500 posts since 2012 with more than half written by community members. The long form blog posts are for a broad readership, and the shorter tech notes include information on a software release with major new features, breaking changes, or significant new documentation for example.

This list gives you a taste of some themes. Click on a topic below to see some of our favorite examples.

There are many ways to explore our blog and tech notes content:

3.4.1 How to contribute?

  • Read blog posts or tech notes
  • Did you find an article interesting or useful? Share posts with your network
  • Comment on a post to share your perspective or to ask a question. Comments appear in our public discussion forum.
  • We love to hear stories about how people use our tools and resources. Have an idea for our blog? Write a blog post or tech note. Take a look at examples of posts above and on the blog, browse the Blog Guide to see what’s involved, then contact our Community Manager, Stefanie Butland, via Slack or our contact form to propose and discuss your idea.

3.5 Blog Guide

Our Blog Guide is written to help authors and editors of rOpenSci blog posts and tech notes to address frequently asked questions, and frequently given suggestions. We created it after reviewing and publishing over 100 posts by community members.

Chapter 1 coaches you in thinking through what you might say in a post and points to examples on different themes. Chapter 2 provides detailed technical guidelines for submitting a post - from drafting in an R Markdown or Markdown template to submitting it for review using GitHub pull request infrastructure. We provide templates, code snippets, our style guide, and checklists to help. One chapter provides some motivation for doing the extra work to contribute a post by outlining what we do to promote it to our large audience. Another outlines how to respond to an editor’s review of your draft post.

3.5.1 How to contribute?

3.6 Packages & Docs

The Packages page on our website lists our carefully vetted, staff- and community-contributed R tools that lower barriers to working with open data sources for various research applications. Of over 400 packages, about 30.0% have been peer reviewed, and more than half are on CRAN.

The list is maintained in our registry, which contains much more metadata about the packages. Documentation for rOpenSci packages is built and hosted at an automated documentation server (docs.ropensci.org; docs repository).

You can discover packages by searching with a package name, name of the maintainer (maybe you’re a fan of their work), or by keywords in the description such as “taxonomy” or “weather”. Clicking on any package row expands the listing to include a package description and list of academic citations. Clicking on the “View Documentation” Button takes you to the docs page where you can find information on using the package from Getting Started, Articles and Vignettes, and on making contributions from reporting bugs, to submitting feature requests or bug fixes. If present, clicking on the “Peer-reviewed” badge will bring you to the peer-review discussion thread.

Screen shot of packages list showing expanded information on the bomrang package and what to click to access different information

Often the best way to start learning about a package is to install it, and start playing with it. Try some of the examples, maybe on your own data, or with your own use case. You can learn more about how to use a package by reading blog posts and tech notes tagged with package names (like tesseract or taxize). Browse the tags page to find posts. Find examples of how others use them by browsing the UsesCases category of our public forum. Some of our Community Calls focus on packages in a specific domain. Check out our archive with videos of past calls. Looking for more examples? Ask in the forum.

Most developers are interested to hear from you while you’re getting to know a package. Is there something unclear in the documentation? Some parts of the software you find confusing? It’s helpful if you share these experiences. When possible, use a “reprex”, a reproducible example.

While package maintainers have the ultimate say on package features, they are often eager to modify a package to accommodate real world use cases. If you have a particular feature request in mind, open an issue in the package repository with a succinct idea, and ideally a minimal reproducible example if code is applicable. Avoid emailing maintainers directly - it may be tempting but benefits no one else. For some, it’s a challenge to have the confidence to make your suggestion in the open, but taking that step can help others. This also helps maintainers manage their work by keeping communications within the GitHub infrastructure that houses the package.

You can also help out by addressing issues (see the Issues List), or making pull requests to add features, fix bugs, add documentation, or add vignettes or articles. To do so, take a look at the project’s contributing guide (here’s a nice example from Peter Desmet, and another from Noam Ross), then open an issue to discuss your approach with the author. Create a pull request and submit your proposed solution!

3.6.1 How to contribute?

  • Browse rOpenSci packages
  • Browse package Task Views
  • Use an rOpenSci package (Yes, that is a contribution!)
  • Tell a friend about an rOpenSci package that may be useful for their work
  • Browse citations of rOpenSci packages to find interesting applications
  • Cite rOpenSci packages in manuscripts and presentations and encourage your colleagues to cite software. Manuscript citations will appear on our packages page.

Just learned that the webchem package was cited in a paper by a group of oncologists. It totally made my morning to think that my code might someday contribute a teensy tiny bit to better treatments for cancer.
Eric Scott on Twitter

  • Write a post about using rOpenSci packages on your own blog
  • Report a bug by opening an issue. If you’re asking for R help, reporting a bug, or requesting a new feature, you’re more likely to succeed if you include a good reprex (a reproducible example).
  • Review the documentation and give feedback to the author in an issue on any parts that are confusing
  • Make a pull request to fix a typo or a bug, to add/fix examples, to add/clarify documentation, to add/update a citation file
  • Make a feature request by opening an issue in a package that’s critical for your work
  • Write a vignette/article for a package. Contact the package author, preferably in an issue, to confirm they are receptive, propose your idea, and determine how they will review your contribution.

3.7 Task Views

Task views are excellent resources for guidance on which packages are relevant to a certain topic. They might list packages under sections like data retrieval, visualization, or analysis. Here we list some task views maintained by rOpenSci staff and community members. They contain packages that are on CRAN and/or on GitHub.

You can contribute to task views by looking at the project’s contributing guide, then comment in an issue to discuss your approach with the maintainer. Create a pull request and submit your proposed changes! If you have a problem with one of the packages discussed it’s best to contact the maintainer of that package directly.

Taxonomy, maintained by Scott Chamberlain, contains information on retrieving and manipulating taxonomic data in R.

Antarctic and Southern Ocean Science, maintained by Ben Raymond, covers a range of topics within the geosciences, life sciences, physical sciences, and humanities and social sciences of particular interest to Antarctic and Southern Ocean researchers.

Hydrological Data and Modeling, maintained by Sam Zipper, Sam Albers, and Ilaria Prosdocimi, contains information about packages broadly relevant to hydrology, defined as the movement, distribution and quality of water and water resources over a broad spatial scale of landscapes. The maintainers built on this task view in “Getting your toes wet in R: Hydrology, meteorology, and more”.

Archaeological Science, maintained by Ben Marwick, contains packages useful for scientific work in Archaeology, grouped by topic.

Web Technologies and Services, maintained by Scott Chamberlain, Thomas Leeper, Patrick Mair, Karthik Ram, and Christopher Gandrud, contains information about how to use R and the world wide web together. It focuses on packages for obtaining web-based data and information, frameworks for building web-based R applications, and online services that can be accessed from R.

3.7.1 How to contribute

  • Browse existing Task Views to discover packages to use.
  • Make a pull request to add packages or details to an existing task view after discussing your approach with the maintainer.

3.8 Use cases

You can find use cases for rOpenSci packages and resources in our public forum UseCases category.

A “use case” here is a write-up of an example, including an explanation of what you did, some code, and where possible, an image showing an outcome. It might take the form of a code snippet, or a link to a blog post or to an analysis in a public repository.

Many of these use cases include applications in academia, industry, government, or “just for fun” with examples on biodiversity, ecology, text processing, bibliometrics, workflows and reproducibility, weather, public health, bicycle networks, agronomy, epidemiology, surveys, seafood mislabelling, tweets about fires, and others! Topics in this forum are tagged with the names of rOpenSci packages they address. Clicking on a tag will show you all other posts in the forum that share that tag. You can also search with terms like “weather” or “doi” to find use cases in an area of application. Some use cases outline examples of how resources like our guide on package development, review and maintenance have been used independently of rOpenSci. Read more in our blog post, What are Your Use Cases for rOpenSci Tools and Resources?

We love it when people share their use cases. For so many reasons.

It’s valuable to both users and developers of a package to see how it has been used “in the wild”. This goes a long way to encouraging people to maintain their package knowing there are others who appreciate, use, and build on their work. This also helps people imagine how they might use a package to address their research question, and provides some code to give them a head-start.

Developers and users will thank you and you’ll get the credit and some visibility for your work!

3.8.1 How to contribute

  • Explore use cases in our public forum UseCases category. Comment on or [emoji heart] use cases that you find useful or inspiring. Consider tweeting or sharing to other platforms if you find them particularly helpful.
  • We’ve made it easy to submit your use cases for rOpenSci packages (including your own) or resources by creating a template to guide you. When you post your use case in the forum we’ll tweet about it to rOpenSci’s ~30,000 followers, tagging you and the package or resource author, and we might feature it in our newsletter.
  • Encourage your peers to submit use cases. Over time, these “small” actions are creating valuable open resources!

Screen shot of the use case template

Use case template

3.9 Issues list

Here we describe how to find and consider working on open issues in rOpenSci projects. In 2019, 117 people made their first-ever code contribution to rOpenSci! The rOpenSci issues list is a dynamic page showing all open issues in the “rOpenSci GitHub organization”.

Issues in GitHub are used to track ideas, enhancements, tasks, or bugs. For general information on using issues see the documentation on Managing your work with issues, and the GitHub Guide Mastering Issues. Issues can be opened by anyone - the package maintainer, a user reporting a bug or something in the documentation that’s confusing, or a person proposing their idea for contributing. For more sources of information on using GitHub see Communication channels.

Many of our packages are developed by busy community members working in research environments in which software development is a voluntary, side project. These developers often appreciate help in addressing open issues in their packages. These can involve either code or non-code contributions. Some will be suitable for beginners and some will require more experience. To contribute, see if there is an issue that interests you, take a look at the project’s contributing guide, then comment in the issue to discuss your approach with the maintainer. Once your proposed plan is accepted by the maintainer, create a pull request and submit your solution. Don’t be discouraged if you don’t get an immediate response. It will depend on the popularity of a package and whether maintaining it is part of a person’s “day job”.

One way to narrow down your search for open issues is to search for labels.

  • help wanted (GitHub search terms org:ropensci label:"help wanted" state:open)
  • good first issue (GitHub search terms org:ropensci label:"good first issue" state:open)
  • documentation (GitHub search terms org:ropensci label:"documentation" state:open)
  • feature (GitHub search terms org:ropensci label:"feature" state:open)

You can also combine labels in a search.

Find all open issues in rOpenSci with org:ropensci state:open https://github.com/search?q=org%3Aropensci++state%3Aopen&type=Issues

Non-coding “help wanted” issue

Non-coding “help wanted” issue

Coding “help wanted” issue

Coding “help wanted” issue

Are you a package author who wants to encourage people to help with issues in your project? Consider making your packages “contribution and collaboration friendly” by including a code of conduct, a contribution guide, and by labelling issues as suggested above. Some good examples of contribution guides are this one from Peter Desmet, and this one from Noam Ross.

3.9.1 How to contribute?

  • For package authors: Label your issues so people interested in contributing can find them. We recommend “help wanted” (no hyphen), “good first issue”, “beginner”
  • For package authors: Include future plans for your package in the README and open issues to address aspects of your plan.
  • Address a “Help wanted” issue. Take a look at the Issues List. If you see one that interests you, take a look at the project’s contributing guide, then comment in the issue to discuss your approach with the author. Create a pull request and submit your solution!
  • Address any open issue. The majority of issues are not labelled “help wanted” but that doesn’t mean the author wouldn’t appreciate your help. Browse the issues in a package you use and see if there’s one you could address. This is a great way to get your favorite packages work the way you want them to!

3.10 Dev Guide: Development, maintenance, and peer review of rOpenSci packages

Our online guide “rOpenSci Packages: Development, Maintenance, and Peer Review” a.k.a. the “Dev Guide”, is a resource for authors, maintainers, reviewers and editors of rOpenSci packages.

rOpenSci has been running a software peer review system since 2015 to combine the best of academic peer review with software review. Having robust and reliable software tools is an important component of supporting open science and reproducible research. The Dev Guide was developed as a resource to help support and streamline these efforts and to promote best practices. It contains a huge amount of information including:

Are you wondering what it’s like to review a package for the first time, or how long it might take? Explore the Dev Guide sections on Why submit your package to rOpenSci? and Guide for Reviewers. Read blog posts with the “reviewer” tag. Many people review an R package before ever making one. Check out the list of past reviewers. Maybe you know one of them and can ask about their experience.

As a useR, you are qualified as a potential package reviewer if you have some appreciation for what makes your favourite packages useful.
Miles McBain in “Where is the value in package peer review?”

If you’re interested in submitting a package for peer-review, read the Dev Guide section Why review packages for rOpenSci? or read blog posts with the “software-peer-review” tag to get the perspectives of authors whose packages have passed peer review as well as learn about the process itself.

Once you’ve submitted your package and an editor has assigned reviewers, you and the reviewers will be invited to join rOpenSci’s Slack workspace where you can connect more directly with members of the rOpenSci community, including other reviewers, package authors, users, and the rOpenSci staff and leadership team.

When you submit your package for review, consider also publishing a journal article about your package. We have collaborative agreements with two journals. If you choose to submit an article to the Journal of Open Source Software (JOSS), it will be evaluated by JOSS based on the completed rOpenSci review. To submit to Methods in Ecology and Evolution, you can submit to a joint review process whereby your package is reviewed by rOpenSci, followed by a fast-tracked review of the manuscript by Methods in Ecology and Evolution.

Finally, make sure your package is easily citable to get credit for all your hard work! Use the use_citation() function from the usethis package to add a CITATION file so users can use citation("yourpackage") to easily find how to best cite your package. It’s also useful to add a section to your README letting users know how you’d like them to cite your package.

Sometimes an rOpenSci package maintainer finds that maintaining a package is no longer feasible for them. When that happens, we work hard to find new maintainers. If you think you might be interested, the Dev Guide Chapter on Changing Maintainers is a good place to start. If taking on a whole package seems like a bit much, check out our “Issues” section here to find specific issues you could help tackle in a package.

For the big picture, watch the video of Noam Ross’s useR! 2020 keynote, “Peer-Reviewing R Code: Where We’ve Been and Where We’re Going at rOpenSci”

Read how our Dev Guide has been used in the wild in a manuscript review: When Standards Go Wild - Software Review for a Manuscript, and in the core curriculum of a Master of Data Science program: Using rOpenSci Software Peer Review Guidelines for Teaching.

3.10.1 How to contribute

3.11 Statistical Software Peer Review Book

We invite you to join us in developing new standards for peer-reviewed evaluation of statistical software. Learn about this work in progress at rOpenSci Statistical Software Peer Review.

Until recently, rOpenSci’s software peer review program focused on R packages for reproducible data life cycle management. To apply these processes to software implementing statistical methods and algorithms, we need new ways of evaluating and testing software, and of managing the review process, and to bring in new expert editors and reviewers. This book serves as a home for collecting research and developing those standards, documenting not only our guidelines for statistical software but also the process of expanding the scope of review so the general processes of software review may be adapted and reproduced in other domains.

This work is supported by the Sloan Foundation and is organized under an R Consortium Working Group.

3.11.1 How to contribute

3.12 Contributing Guide

This book you’re reading right now is the rOpenSci Community Contributing Guide. Its purpose is to welcome you to rOpenSci and help you recognize yourself as a potential contributor. It will help you figure out what you might gain by giving your time, expertise, and experience, match your needs with things that will help rOpenSci’s mission, and connect you with resources to help you along the way.

This Guide is an evolving document and we want people to tell us what’s missing or what’s not clear.

3.12.1 How to contribute