production.qmd

---
title: "Production repository"
---

```{r, eval = TRUE, echo = FALSE}
source("R/utils.R")
```

The Production repository comprises a subset of [Community](community.md) package releases
which are mutually compatible and meet a high standard of quality.

## Users

Production deploys in periodic snapshots throughout the year (details below).
The current Production snapshot was created on `r snapshot_date()` when base R had version `r snapshot_r()`.
All packages passed automated checks at that time.
However, the same checks might not pass using a different version of R or
different versions of dependencies from [CRAN](https://cran.r-project.org/).

For the current snapshot, please use R version `r snapshot_r()` and [CRAN](https://cran.r-project.org/) dependencies
from `r snapshot_date()` to ensure compatibility.
[Posit Public Package Manager (p3m)](https://packagemanager.posit.co) can help.
Example:^[Caveat: when setting two URLs in the repos argument, the same package may be in both repositories, and the highest version is always preferred.]

```{r, eval = TRUE, echo = FALSE, results = "asis"}
text <- c(
  "```r",
  "install.packages(",
  "  \"polars\",",
  "  repos = c(",
  "    \"https://production.r-multiverse.org\",",
  sprintf("    \"https://packagemanager.posit.co/cran/%s\"", snapshot_date()),
  "  )",
  ")",
  "```"
)
cat(text, sep = "\n")
```

## Checks

To reach Production, a package release must pass the following R-multiverse checks:

1. `R CMD check` must pass (no errors or warnings) on Mac (R-release), Windows (R-release), Linux (R-devel).
1. The release must not have an active [security advisory](https://github.com/RConsortium/r-advisory-database).
1. The `DESCRIPTION` file must not have a `Remotes:` field.
1. The current version number must be greater than the version numbers of past releases of the same package.
1. The release must not strongly depend (`Depends:`, `Imports:`, `LinkingTo:`) on an R-multiverse package with any any of the above issues.
^[However, an R-multiverse package can strongly depend a package from CRAN, regardless of CRAN check status, as long as that package remains available on CRAN.]

## Snapshots

Once every 3 months, Production updates all its packages simultaneously and deploys a snapshot.
Production does not add, remove, or update packages at any other time.
^[A package is only removed from a snapshot if it becomes absolutely necessary to do so,
e.g. because of an egregious [policy](policies.md) violation.]
Packages change slowly in Production, but they are mutually compatible.
^[And compatible with versions of dependencies that were on CRAN at the time of the snapshot.]

## Staging

Rather than pull releases directly from [Community](community.md),
Production draws from an intermediate repository called [Staging](#staging).
The [Staging](#staging) repository is active during the month-long period prior to each snapshot.
During that time, [Staging](#staging) stabilizes the Production candidates
while still allowing bug fixes.

While [Staging](#staging) is active, if a package is failing one or more [R-multiverse checks](#checks),
then new releases of that package are continuously pulled from [Community](community.md).
Otherwise, [Staging](#staging) freezes the package at its current release
and no longer accepts updates from [Community](community.md).
This freeze prevents new problems in reverse dependencies downstream.

At snapshot time, Production creates the snapshot from the subset of package releases in
[Staging](#staging) which pass [R-multiverse checks](#checks).
A month after the snapshot, [Staging](#staging) resets (removes all its packages)
so that an entirely new set of [Community](community.md) releases can become candidates for Production.

## Schedule

Every year, [Staging](#staging) and Production follow a schedule given by the dates below.

| Quarter | [Staging](#staging) resets | [Staging](#staging) becomes active | Production snapshot |
|---|---|---|---|
| Q1 | December 15 | January 15 | February 15 |
| Q2 | March 15 | April 15 | May 15 |
| Q3 | June 15 | July 15 | August 15 |
| Q4 | September 15 | October 15 | November 15 |

## Status

R-multiverse has a [status system](https://r-multiverse.org/status/index.html) to broadcast the latest [R-multiverse check results](#checks) of each package.
In each of [Community](community.md) and [Staging](#staging), there is an HTML page for every package.
Example:

* <https://r-multiverse.org/status/community/polars.html>
* <https://r-multiverse.org/status/staging/polars.html>

In addition, each package has an RSS feed that updates on each new package release to each repository:^[except in Staging when Staging is currently inactive.]

* <https://r-multiverse.org/status/community/polars.xml>
* <https://r-multiverse.org/status/staging/polars.xml>

## Debugging

`R CMD check` errors in [Staging](#staging)
may be difficult to diagnose. 
For example, [Staging](#staging) might have different versions
of dependencies than you have on your local machine.

The [`packages.json`](https://github.com/r-multiverse/staging/blob/main/packages.json)
file has all the Git commit hashes
of all the versions of packages in [Staging](#staging).
If you can identify the specific
dependency that is causing problems, you can install the version in [Staging](#staging)
and reproduce the issue locally.
For example, if [`packages.json`](https://github.com/r-multiverse/staging/blob/main/packages.json)
lists a dependency:

```json
  {
    "package": "polars",
    "url": "https://github.com/pola-rs/r-polars",
    "branch": "a76b8d56e6f39a6157880069f9d32f3cc1f574d7"
  },
```

then you can install the version of that dependency from R:

```r
pak::pkg_install("pola-rs/r-polars@a76b8d56e6f39a6157880069f9d32f3cc1f574d7")
```

then restart R and run the following to reproduce the issue:

```r
devtools::check("yourPackage")
```

Alternatively, you can create your own personal [universe](https://r-universe.dev),
give it a strategic subset of dependencies from
[`packages.json`](https://github.com/r-multiverse/staging/blob/main/packages.json),
and omit the `"branch"` field from your package so the checks run on every commit.
Visit <https://ropensci.org/r-universe/> to learn more about using R-universe directly.