Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
162 lines (130 loc) · 5.72 KB

CONTRIBUTING.md

File metadata and controls

162 lines (130 loc) · 5.72 KB
Raw

Contributing to pizzarr

Branching and Release Model

pizzarr uses three branch types tied to its two distribution tiers (CRAN and r-universe).

  • develop — active development. All pull requests should target develop, not main. DESCRIPTION carries a .9000 suffix (e.g., 0.2.0.9000) and Cargo.toml uses a -dev pre-release tag (0.2.0-dev).
  • release/X.Y.Z — release candidate. Cut from develop when ready to ship. The .9000 / -dev suffixes are dropped and NEWS.md is finalized. For a CRAN release, the CRAN tarball is built with bash tools/cran-build.sh. This branch is PR'd to main.
  • main — release-only and the GitHub default branch. Always matches the latest release, whether that release went to CRAN and r-universe or to r-universe alone. r-universe auto-builds from main; its binaries include the compiled zarrs Rust backend. pkgdown deploys from main.

A release goes to both tiers or to r-universe only. An r-universe-only release is a full release, not a preview: use it when the changes do not need to reach CRAN, such as Rust dependency updates, zarrs backend fixes, or fixes that can wait for the next CRAN release.

The release sequence:

  1. Development proceeds on develop (version X.Y.Z.9000).
  2. Cut a release/X.Y.Z branch from develop. Drop the .9000 / -dev suffixes and finalize NEWS.md. For an r-universe-only release, say so at the top of the NEWS.md section.
  3. Open a PR from release/X.Y.Z to main.
    • CRAN and r-universe: build the CRAN tarball with bash tools/cran-build.sh and submit it. Do not merge until CRAN has accepted the package.
    • r-universe only: merge once CI passes. No CRAN submission.
  4. After merging, r-universe picks up the new commit on main and builds binaries with the zarrs backend. pkgdown rebuilds.
  5. Merge main back into develop and bump the version to the next X.Y.Z.9000.

After an r-universe-only release, r-universe carries a newer version than CRAN until the next CRAN release. The builds also differ: CRAN gets pure R (no Rust), r-universe gets the zarrs backend. Users can check which tier they have with pizzarr_compiled_features().

Development Setup

# make sure you are on the develop branch
setwd("path/to/pizzarr")
install.packages("devtools")
devtools::install()
devtools::load_all()

Build and Test Cycles

pizzarr has two build tiers that affect how you develop and test locally.

CRAN tier (pure R)

If you are working on R-side logic (indexers, stores, codecs, R6 classes) and do not need the zarrs backend, this is the faster cycle:

devtools::load_all()
devtools::test()
devtools::check()

Tests run single-threaded (Config/testthat/parallel: false in DESCRIPTION). All zarrs-specific tests skip automatically when the Rust library is absent — they guard on .pizzarr_env$zarrs_available.

To produce a CRAN-ready source tarball that strips src/, configure, and SystemRequirements:

bash tools/cran-build.sh

The resulting .tar.gz passes R CMD check without a Rust toolchain.

r-universe tier (zarrs backend)

The r-universe build compiles the zarrs Rust crate via extendr. You need rustc >= 1.91 with the GNU target on Windows:

rustup target add x86_64-pc-windows-gnu

After modifying any #[extendr] function in src/rust/src/lib.rs, regenerate the R wrappers:

rextendr::document()

This rebuilds the Rust library and regenerates R/extendr-wrappers.R. Never edit that file by hand. Then run the standard cycle:

devtools::load_all()
devtools::test()
devtools::check()

devtools::check() will emit a NOTE about downloading Rust crates — that is expected and is not a problem for r-universe builds. See RUST-STYLE.md for Rust conventions, module layout, and build pipeline details.

Building Documentation

devtools::document()
pkgdown::build_site()

Coding Conventions

  • Style: snake_case everywhere (functions, methods, variables). 2-space indent.
  • Errors: stop("ErrorName(details)") — mimics Python Zarr error names. No rlang.
  • Warnings/info: warning() and message() from base R.
  • Assertions: direct if (...) stop() — no assertion library.
  • R6 docs: roxygen2 with @title, @docType class, @format [R6::R6Class]. See r6-roxygen-convention.md for the full style guide.
  • Tests: testthat 3e with test_that("description", { ... }).

Resources