How to cut a tagged release of the two shippable artifacts — the miniextendr CLI (a Rust binary) and rpkg (the R package, which installs as library(miniextendr)). There is no release-automation workflow today; releases are manual tag-and-push. This document is the recipe.

Not to be confused with RELEASE_WORKFLOW.md, which is about the CI workflow downstream consumers scaffold (minirextendr::use_release_workflow()) — not about releasing miniextendr itself.

🔗Release gates

A release commit is tagged only after it passes the release column of the CI and release gates on that exact commit. The release checklist walks through it and ends with the tag commands. GitHub enforces none of this; nothing is a required check on main yet (#1391).

🔗Version bumping

One script bumps every version-bearing file in lockstep:

just bump-version 0.2.0        # or: bash scripts/bump-version.sh 0.2.0

It updates [workspace.package].version in the root Cargo.toml (which the CLI inherits via version.workspace = true) and the Version: field of every DESCRIPTION (rpkg, minirextendr, the cross-package test fixtures). Commit the result on a branch and land it on main through a pull request. Tag the merged commit only after the release gates pass on it; the release checklist ends with the tag commands.

🔗Releasing the CLI

The CLI is a plain binary crate ([[bin]] name = "miniextendr"). Its only dependencies are crates.io packages — it does not depend on miniextendr-api/-macros, so it has no vendoring or git-pin entanglement.

Once the tag is pushed, users install straight from it — no crates.io publish, no CI infrastructure required:

cargo install --git https://github.com/A2-ai/miniextendr --tag v0.2.0 miniextendr-cli
# add --features dev for the contributor-only `dev` subcommands

cargo install --path miniextendr-cli (or just cli-install) remains the from-checkout path for local development.

crates.io publishing is not set up. The crate carries no publish = false, so it could be published, but the git-tag install above covers distribution without it.

🔗Releasing rpkg

rpkg ships in two modes, and they behave differently. Both start from the pushed tag above.

🔗Mode A — GitHub source install (remotes/pak/devtools)

remotes::install_github("A2-ai/miniextendr", subdir = "rpkg", ref = "v0.2.0")
# pak::pak("A2-ai/miniextendr/rpkg@v0.2.0")

remotes downloads the whole-repo zipball (no .git) — so the framework crates (miniextendr-api, -lint, -macros) travel along as sibling directories — and builds via pkgbuild. Because DESCRIPTION sets Config/build/bootstrap: TRUE, pkgbuild runs rpkg/bootstrap.R first.

On the default build = TRUE path, pkgbuild runs bootstrap.R, which never vendors. Only a path dependency outside the package (path = "../…", which a staged/git install would strand) needs work: tools/dev-bootstrap.R stages those crates under src/rust/vendor/ with cargo package (#1580), and registry and git dependencies resolve over the network. A package whose path dependencies all live inside it (the exemplar’s satellite) or that has none (the typical scaffold) falls through to a plain source build (configure’s [patch] for the framework siblings, or cargo fetching the git URL). cargo-revendor is never involved.

How the framework crates resolve (read from configure.ac):

  • configure detects the monorepo by a filesystem probe — it walks up ≤5 levels looking for miniextendr-api/Cargo.toml (configure.ac:463–473), not by a .git ancestor. The full-repo zipball satisfies this, so the siblings are found and (in pure source mode) a [patch."https://github.com/A2-ai/miniextendr"] block redirects the three crates to those local, tag-state sources.
  • The framework version is pinned by the committed src/rust/Cargo.lock (shipped via Config/build/extra-sources); its framework entries carry source = "git+…#<sha>", and the vendor/offline branch reproduces that sha. The unpinned git = … in Cargo.toml only decides resolution when the lock is regenerated — see “Known gap”.

Prerequisites: Rust toolchain (SystemRequirements: Cargo, rustc >= 1.85) and network access. cargo-revendor is not needed. autoconf is not needed — configure is committed.

🔗Mode B — released vendored tarball (reproducible, offline, CRAN-shaped)

This is the recommended release artifact. Vendoring is an explicit step that only the release build runs; devtools::build() alone produces a Mode A (source-mode) tarball.

just r-cmd-build               # → miniextendr_0.2.0.tar.gz, vendored

just r-cmd-build (and just r-cmd-check) run just vendor first, which writes inst/vendor.tar.xz with cargo-revendor and asserts that the framework crates were vendored from the local workspace rather than git@main (#876). The recipe removes the archive and restores the committed Cargo.lock when it exits. A scaffolded package does the same with minirextendr::miniextendr_build_tarball(). This needs cargo-revendor on PATH. Before attaching a tarball, confirm it contains inst/vendor.tar.xz (tar -tzf … | grep inst/vendor.tar.xz).

Attach the resulting miniextendr_0.2.0.tar.gz to a GitHub Release. Users install it offline and reproducibly:

install.packages("miniextendr_0.2.0.tar.gz", repos = NULL, type = "source")
# remotes::install_url(".../releases/download/v0.2.0/miniextendr_0.2.0.tar.gz")

At install, configure detects inst/vendor.tar.xz — the single latch — and switches to tarball mode: offline build from vendored-sources, no network, no cargo-revendor.

Why prefer this over Mode A: the tarball is self-contained and offline — vendored sources are sealed inside, so the user needs no network and no cargo-revendor, and the framework code is frozen at build time (built inside the monorepo, configure writes a [patch."git+url"] override and cargo-revendor vendors the framework crates from the local checkout). Mode A is a from-source build that still depends, at the user’s machine, on a Rust toolchain, network access, and the committed lock sha.

Building release artifacts on CI (esp. macOS): the Rust toolchain ABI must match CRAN’s R, or the .so fails to load / trips --as-cran. configure bakes a per-install MACOSX_DEPLOYMENT_TARGET floor into .cargo/config.toml (configure.ac:520–577), but a release runner should also pin the SDK. See RELEASE_WORKFLOW.md Gotchas 5–6 — and note minirextendr::use_release_workflow(rpkg_subdir = "rpkg") scaffolds a known-good workflow for this exact subdir layout.

🔗Known gap

The framework git dependencies in rpkg/src/rust/Cargo.toml (and the tests/model_project / minirextendr fixtures) are declared unpinned (git = "…", no tag/rev). Reproducibility today rests entirely on the committed Cargo.lock sha — not the manifest. If anything regenerates the lock during a release build (a cargo update, or a cargo old enough to rewrite a v4 lock — see configure.ac:920), the framework jumps to whatever main HEAD is at that moment, silently. Pinning tag =/rev = in the manifest would make the release self-describing instead of lock-dependent. Track as an issue rather than leave implicit.