Contributors

This page explains how to contribute packages to R-multiverse.

Preparation

R-multiverse policies govern all forms of participation in R-multiverse, including package contributions. Administrators, moderators, and contributors are all subject to the terms therein. The review policy specifically governs package contribution and review. In particular, please ensure your package has a valid free open-source (FOSS) license and a formal release.

You can run multiverse.internals::review_package() to check if your package is compliant. For example:

install.packages(
  "multiverse.internals",
  repos = c("https://community.r-multiverse.org", getOption("repos"))
)
multiverse.internals::review_package(
  name = "polars",
  url = "https://github.com/pola-rs/r-polars"
)

Not all findings are problems, but some may delay the acceptance of your package.

Registration

To register a package with R-multiverse:

  1. Navigate to https://github.com/r-multiverse/contributions.
  2. Contribute a package listing via GitHub pull request.

Watch this 1-minute video to learn how:

Package listings

A package listing is a text file in https://github.com/r-multiverse/contributions/tree/main/packages which points to the home of the package on GitHub/GitLab. The file name of each listing is the name of the package. In most cases, the file itself contains the package URL on GitHub or GitLab (example). But if the package is a subdirectory of the GitHub/GitLab repository, you may instead write custom JSON list with fields package, url, subdir, and branch: "*release" (example).

Pull request review

A pull request in https://github.com/r-multiverse/contributions/pulls is reviewed by a bot and usually by a human moderator. If the pull request author is a public member of one of these GitHub organizations, then the bot may skip the human and accept the contribution automatically. This privilege is a special level of trust we extend to accountable human members of known reputable communities. You may propose a new organization via pull request, and the administrators will confidentially discuss the security implications before deciding whether to add it.

Some moderators only review packages specific to a subject matter area, so please consider mentioning a topic in the title of the pull request.

Community

After registration, the latest GitHub/GitLab release of the package will automatically appear in the Community repository, and you will see it in the dashboard at https://community.r-multiverse.org. This process is facilitated by public GitHub Actions workflows on both R-multiverse and R-universe1, and it may take a few hours.

Updating your package

To update your package to a new version on R-multiverse, simply create a new release on GitHub or GitLab. usethis::use_github_release() makes this process easy for packages hosted on GitHub.2 If you instead create the release manually in the GitHub.com web interface, please be sure to set the new release as the latest release. Sometimes the newest release does not automatically become “latest”. On GitHub, there is an important check box near the bottom of the web form:

After you create the release, you should see a “Latest” label on the right-hand side of the title.

If successful, the new version of your package should appear at https://community.r-multiverse.org after the Community universe automatically refreshes.

Production

R-multiverse updates the Production repository in quarterly snapshots. The Production status page list the packages successfully staged for the next Production snapshot. Visit the Production documentation to learn how the process works.

Checks

Before you release a new version of your package, you can check the development version in an environment that approximates Staging. This will help you pass checks and get into Production.

If you host your source code on GitHub, simply add a small workflow file to your package:

usethis::use_github_action(url = "https://github.com/r-multiverse/workflows/blob/main/examples/r-multiverse-staging.yaml")

Then commit that file to GitHub, navigate to the “Actions” section of your repository, and run the r-multiverse-staging workflow:

R CMD check will run on Mac, Linux, and Windows. The workflow uses the same versions of base R and R packages that R-multiverse enforces in Staging.

Status

It is good practice to check the health of your contributed package using R-multiverse status system. You can read more about it here in the Production page.

Topics

R-multiverse has a topics website that organizes packages into subject matter areas. Each topic has a page that lists the packages in its area (example). To contribute a package to a topic, simply list the topic URL in the DESCRIPTION file (example). and then create a new GitHub/GitLab release. To contribute a topic, submit a pull request to add a new topic listing file that describes the new topic. A scheduled job periodically rebuilds the website from the listings.

Badges

R-multiverse status

To add a dynamic ‘R-multiverse’ badge for package readme files, like the one above, copy the following markdown snippet, replacing ‘pkgNAME’ with the actual package name in both places it appears:

[![R-multiverse status](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcommunity.r-multiverse.org%2Fapi%2Fpackages%2FpkgNAME&query=%24.Version&label=r-multiverse)](https://community.r-multiverse.org/pkgNAME)

Installation instructions

In the README of your package, it is good practice to include installation instructions (example). Please see the overview page for general instructions on installing packages from R-multiverse. Feel free to adapt these instructions for your own package.

Deregistration

If it becomes necessary to deregister a package from R-multiverse, you may submit a pull request to edit the package listing. Please replace the URL/JSON contents with unstructured/free-form text to explain the reason for removing the package. To prevent a package of the same name from registering in R-multiverse, please do not delete the package listing file unless the package name itself violates R-multiverse policies. Packages with missing or free-form listings are removed from Community, and the subsequent Production snapshot will not include them.

Help

Please report bugs to https://github.com/r-multiverse/help/issues and send other feedback and questions to https://github.com/r-multiverse/help/discussions. Please note that https://github.com/r-multiverse/contributions can only accept pull requests to add or modify package entries.