Internal NSWERS R Packages

Background Context

Previously, the use of NSWERS internal R packages has been somewhat fragile.

• For example, running remotes::install_git("https://NSWERS@dev.azure.com/NSWERS/Research/_git/packagename", git = "external") can be fragile, because two people running this command on different dates may end up with different versions of the package installed.
• Referencing a specific commit improves reproducibility, but it introduces a different problem: knowing which commit should be used.

Formal releases with semantic versioning are the ideal long‑term solution. In the R ecosystem, the standard approach is to use a public repository such as CRAN, Bioconductor, or possibly rOpenSci. However, our packages cannot be published on CRAN or similar public repositories because they contain proprietary resources (e.g., RDB links). Therefore, we need an alternative mechanism to release and distribute these packages.

Azure Artifacts Universal Packages

The chosen solution is publishing the packages as Universal Packages in Azure Artifacts. This represents a local optimum across several desirable properties:

• Fits within our existing technology stack
• Already integrated with Azure, which we actively use
• Each package version can be released only once
• Prevents overwriting of existing version numbers
• Supports automated releases via pull requests and CI actions
  • In practice, a PR to main plus a tagged commit triggers a build and release
• Supports script- and command-line-based installation
• Does not require manual downloads
• Authentication and authorization are relatively painless
• Works with other toolchains
  • In particular, it integrates well with renv

All NSWERS internal packages are available today in this Azure Artifacts framework: https://dev.azure.com/NSWERS/Research/_artifacts/feed/nswers_r_internal

Package Installation

To install packages from this system, you must first download the files to your local environment and then install them.

1. Download (using a terminal, e.g., Git Bash)
   • On the Windows platform , log into the Azure CLI.
   • Download a package by providing the appropriate arguments for name, version, and path.

### On the Windows platform, log into the Azure CLI
az login

### Download a package by providing the proper arguments to name, version, and path
az artifacts universal download \
  --organization "https://dev.azure.com/NSWERS/" \
  --feed "nswers_r_internal" \
  --name "package_name" \
  --version "0.0.0" \
  --path "path/to/package"

2. Install (using R script)
   • You can install the package using install.packages(), renv::install(), or similar tools.
   • The download includes both the .tar.gz source files and precompiled Windows binaries. The binaries install faster.

# install using .tar.gz
install.packages("path/to/package_name.tar.gz", repos = NULL, type = "source")

# install using binary (.zip)
install.packages("path/to/package_name.zip", repos = NULL, type = "source")

Git Version Release Workflow (using Git Bash)

When you want to update a package, follow these steps to create and publish a version tag (e.g., v2.0.0).

### Make sure you are on main branch
git checkout main

### Make sure you are on up to date with origin
git pull origin main

### Take the current branch/HEAD
git tag -a v2.0.0 -m "Release v2.0.0"

### Push the tag to origin
git push origin v2.0.0

Future Documentation

Documentation still needs to be written for:

1. Adding a new package into this system
2. Releasing a version of a current package
3. Using this with renv (forthcoming)