Release Process#

Audience: maintainers
Time: 10 minutes
What you’ll get: the version sites that move together, and how a release is built and published

To release the R package, publish a GitHub Release vX.Y.Z in theislab/cellucid-r; the workflow release.yaml (“Publish to CRAN”) submits it to CRAN. Nothing else publishes it: pushing a tag does nothing, and the workflow has no manual trigger. Releasing Cellucid covers the three Cellucid packages in order.

The full step-by-step checklist lives in:

  • cellucid-r/publishing.md

Release flow#

  1. Update DESCRIPTION version. It is the one source the rest are checked against.

  2. Update CITATION.cff, NEWS.md, README.md, and vignettes/installation.Rmd to match, plus the pinned release literal in tests/testthat/test-current-contract.R. NEWS.md headings carry no date; CRAN records the publication day.

  3. Record user-visible changes in NEWS.md and keep cran-comments.md current.

  4. Ensure tests pass (testthat::test_local(), including the anndata round trip with CELLUCID_ANNDATA_PYTHON set, and R CMD check --as-cran).

  5. Merge to main and wait for CI to be green there.

  6. Publish a GitHub Release whose tag is exactly v followed by the DESCRIPTION version, on main, not marked pre-release. release.yaml runs on release: published only and, before building anything, refuses a draft, a release marked pre-release, a DESCRIPTION version that is not X.Y.Z (CRAN takes final versions only), a tag other than EXPECTED_TAG="v${VERSION}", and a tagged commit that is not on main.

  7. release.yaml then builds the source tarball, runs R CMD check --as-cran on it, uploads it with its SHA-256 as the r-source-tarball artifact, attaches both to the release and, when the check reports no WARNING and no ERROR, submits the tarball to CRAN with cran-comments.md as the comment (devtools:::upload_cran()); CRAN then emails the maintainer a confirmation link, which the maintainer must click.

  8. A run that failed for a passing reason (a runner, the network, CRAN’s form) is retried with Re-run jobs on that run in the Actions tab.

  9. Other channels follow the GitHub release:

    • r-universe (auto-builds from GitHub once the GitHub App is installed)

    • conda-forge (r-cellucid, built from the CRAN tarball)

pkgdown.yaml separately builds and deploys the package website at https://theislab.github.io/cellucid-r/. That site is the R help pages; this guide is the narrative documentation, and the two are maintained separately.

Keeping this guide’s version in step with the package#

The page you are reading is part of the cellucid-python repository, and so is Installation, which tells R users which version to install. cellucid-python/scripts/validate_release.py checks those pages against the Python package version in cellucid-python/pyproject.toml.

cellucid-r and cellucid-python are separate repositories with separate CI, and neither checkout can read the other. Nothing therefore compares cellucid-r/DESCRIPTION to this guide: bumping the Python version alone leaves every gate green while the R installation page names a version the R package never shipped, and bumping cellucid-r/DESCRIPTION alone leaves this guide behind. The two versions are meant to move together; keeping them together is a manual step in both release checklists.

  • cellucid-r’s own test suite pins DESCRIPTION to every version site inside that repository, and DESCRIPTION carries a Config/cellucid/version-marker field so a grep -rn CELLUCID_VERSION sweep lists it.

  • Releasing either package means bumping both to the same version and running python scripts/validate_release.py in cellucid-python plus testthat::test_local() in cellucid-r.

What contributors should keep in mind#

  • The package writes a standard AnnData store plus uns['cellucid']; the web app and the Python package read and write the same contract.

  • A change to what the store holds lands in the R writer, the Python writer, the web reader, their tests, and the documentation together; only the one current layout is kept.

Where to update docs#

When the store or the arguments change, update:

  • the hand-written help pages under cellucid-r/man/ (cellucid_prepare.Rd, cellucid_view.Rd and the other viewer pages), and the reference index in cellucid-r/_pkgdown.yml when a topic is added (the article index when a vignette is added; .github/scripts/validate-pkgdown.R refuses a site whose indexes miss one)

  • cellucid-r/README.md and cellucid-r/vignettes/cellucid.Rmd (and vignettes/viewer.Rmd for the viewer)

  • user guide API docs: Data Preparation API

  • the store specification: Cellucid-ready AnnData specification (R writer)