5 Publication

openstatsware short course: Good Software Engineering Practice for R Packages

Daniel Sabanés Bové

July 17, 2026

Website with pkgdown

Setup of pkgdown

  • pkgdown makes it quick and easy to build a website for your package
  • After installing pkgdown, run usethis::use_pkgdown() to get started
  • Alternatively, run usethis::use_pkgdown_github_pages()
    • Adds (and writes) pkgdown.yml, docs folder, and “pkgdown” to .Rbuildignore and docs to gitignore. Also initialises empty branch gh-pages in chosen repo and activates GitHub Pages for repo
  • Main configuration happens in _pkgdown.yml file
  • Many customizations can be applied, but bulk of work during development is updating the reference section with names of .Rd files

Example _pkgdown.yml File

---
url: https://openpharma.github.io/mmrm

template:
  bootstrap: 5
  params:
    ganalytics: UA-125641273-1
  math-rendering: "mathjax"

navbar:
  structure:
    left: [intro, reference, articles, tutorials, news, reports]
    right: [search, github]
  components:
    reports:
      text: Reports
      menu:
        - text: Coverage report
          href: coverage-report/
        - text: Unit test report
          href: unit-test-report/
    github:
      icon: fa-github
      href: https://github.com/openpharma/mmrm

articles:
  - title: Introduction
    navbar: Introduction
    contents:
      - introduction
      - methodological_introduction
      - mmrm_review_methods
  - title: Covariance Structures
    navbar: Covariance Structures
    contents:
      - covariance
  - title: Degrees of Freedom and Testing
    navbar: Degrees of Freedom and Testing
    contents:
      - hypothesis_testing
      - between_within
      - kenward
      - satterthwaite
  - title: Coefficient Covariance
    navbar: Coefficient Covariance
    contents:
      - coef_vcov
      - empirical_wls
      - model_robust_estimator
  - title: Algorithm Details
    navbar: Algorithm Details
    contents:
      - algorithm
      - predict
  - title: Developers
    navbar: Developers
    contents:
      - package_structure
reference:
  - title: Package
    contents:
      - mmrm-package
  - title: Functions
    contents:
      - mmrm
      - fit_mmrm
      - mmrm_control
      - fit_single_optimizer
      - refit_multiple_optimizers
      - df_1d
      - df_md
      - component
  - title: Start Values
    contents:
      - std_start
      - emp_start
  - title: Methods
    contents:
      - mmrm_methods
      - mmrm_tidiers
      - mmrm_tmb_methods
      - stats_anova
  - title: Covariance Structures
    contents:
      - cov_struct
      - as.cov_struct
      - format.cov_struct
      - print.cov_struct
      - covariance_types
  - title: Estimate Marginal Means
    contents:
      - emmeans_support
  - title: Datasets
    contents:
      - fev_data
      - bcva_data

---

Source: the mmrm package documentation

Publication as GitHub page

  • It’s helpful for users to read the website online
  • GitHub is very helpful here because:
    • A separate branch, gh-pages, stores the rendered website
    • GitHub actions automatically render the website when the main branch is updated
  • To get started, use usethis::use_pkgdown_github_pages()
    • Or, manually deploy site with pkgdown::deploy_to_branch()

Licensing, open sourcing, versioning

Licensing

  • High level categorization of licenses:
    • “Permissive”: Relaxed. Can be freely copied, modified, published (under the same license).
    • “Copyleft”: Stricter. Same rights need to be preserved in derivative works.
    • Helpful tool: https://choosealicense.com/
  • R itself is licensed under GPL, but packages can choose, e.g.:
    • usethis::use_mit_license() for permissive MIT
    • usethis::use_gpl_license() for copyleft GPL
  • Include minimum version, e.g. GPL (>= 3)

Licensing (cont’d)

  • Need to be careful here when you bundle any code from other software
    • Care must be taken that any copyright/license statements from copied or modified code are preserved and authorship is not misrepresented
  • Are the licenses of your package and the source compatible?
    • e.g. cannot copy/paste code from a GPL package and publish in an MIT package
  • LICENSE file optionally can contain further restrictions of the license

Licensing (cont’d)

  • You don’t have to include a license with your code
  • But: if no license is included, your work is under your exclusive copyright by default
    • This means that nobody else can copy, distribute, modify it
    • Once the work has other contributors (each being a copyright holder for their contributions), that nobody starts including you
    • The consequence is that you cannot copy, distribute, modify other people’s contributions to your project
  • Even if unlicensed code is published in a public repository, as a user, you generally don’t have the permission from the creators of the software to use, modify, or share the software

Open sourcing

  • The easiest way to “open source” your R package is to make the GitHub/code repository public
  • This allows for easy open source contributions from other developers via pull requests
  • Please check with your organization first:
    • Are they ok to publish the software?
    • What is the appropriate copyright holder?
  • Also allows bugs to be filed and to have the GitHub issues page in the package description

Versioning

  • The Version field defines the package version
  • Syntax: Three integers separated by . or -
    • Canonical form is: x.y-z, equivalent to x.y.z
  • Useful conventions of “semantic versioning”:
    • x is major: Increment this for breaking changes
    • y is minor: Increment this for new features
    • z is patch: Increment this for bug fixes only
    • x.y.z.9000 and count up during development
    • usethis::use_version() can help with this

Checks before release

CRAN (The Comprehensive R Archive Network)

  • CRAN is the central repository for R packages
  • It has additional requirements beyond the standard package ones, which are described in the Repository Policy
  • Submitting a package indicates agreement with the policy
  • In particular: “The time of the volunteers is CRAN’s most precious resource, and they reserve the right to remove or modify packages on CRAN without notice or explanation (although notification will usually be given).”

CRAN (cont’d)

  • Only source packages can be submitted
    • But .rda data files are allowed
  • Need single designated maintainer (person, not mailing list)
    • Additional Contact field could be used
  • Citations in author-year style, followed by <doi:...>
  • Reducing run time of tests, checks, examples, vignettes is important
  • Need to provide cross-platform portable code: CRAN runs checks on Windows, Mac, and several Linux distributions

CRAN (cont’d)

❗ A CRAN submission can be punishing, painful, and nerve-racking:

The first release of the rpact package took 5 weeks and 6 submission attempts. Painful experiences:

  • Some Linux machines may generate different random numbers than expected (despite setting a seed)
  • Not only errors and warnings lead to the rejection of a submitted package, but also notes
  • Your local Windows test system may be much faster than the CRAN system (e.g., 5 times)
  • Don’t use “R Package for” in your package title
  • The description of the package must be provided with a DOI reference

CRAN (cont’d)

Example message informing about the rejection of the last rpact submission:

Dear maintainer,

package rpact_3.3.2.tar.gz does not pass the incoming checks automatically, please see the following pre-tests:
Windows: 00check.log Status: OK, Debian: 00check.log Status: OK

Please fix all problems and resubmit a fixed version via the webform.

Best regards,
CRAN teams’ auto-check service

r-devel-windows-x86_64 Check: Result: NA, Maintainer: ‘Friedrich Pahlke’
r-devel-windows-x86_64 Check: Overall checktime, Result: NOTE, Overall checktime 12 min > 10 min
r-devel-linux-x86_64-debian-gcc Check: Result: Note_to_CRAN_maintainers Maintainer: ‘Friedrich Pahlke’

R-Hub to the rescue

R-Hub platforms

library(rhub)
rhub::rhub_platforms()
── Virtual machines ───────────────────────────────────────────────────────────
 1 [VM]  linux
   All R versions on GitHub Actions ubuntu-latest
 2 [VM]  m1-san
   All R versions on GitHub Actions macos-15, ASAN + UBSAN on macOS
 3 [VM]  macos
   All R versions on GitHub Actions macos-15-intel
 4 [VM]  macos-arm64
   All R versions on GitHub Actions macos-latest
 5 [VM]  windows
   All R versions on GitHub Actions windows-latest

── Containers ─────────────────────────────────────────────────────────────────
 6 [CT]  atlas  [ATLAS]
   R Under development (unstable) (2026-06-21 r90185) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/atlas:latest
 7 [CT]  c23  [C23]
   R Under development (unstable) (2026-03-14 r89623) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/c23:latest
 8 [CT]  clang-asan  [asan, clang-ASAN]
   R Under development (unstable) (2026-07-17 r90265) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang-asan:latest
 9 [CT]  clang-ubsan  [clang-UBSAN, ubsan]
   R Under development (unstable) (2026-07-17 r90265) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang-ubsan:latest
10 [CT]  clang16  [clang16]
   R Under development (unstable) (2026-03-15 r89629) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang16:latest
11 [CT]  clang17  [clang17]
   R Under development (unstable) (2026-03-15 r89629) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang17:latest
12 [CT]  clang18  [clang18]
   R Under development (unstable) (2026-03-14 r89623) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang18:latest
13 [CT]  clang19  [clang19]
   R Under development (unstable) (2026-03-15 r89629) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang19:latest
14 [CT]  clang20  [clang20]
   R Under development (unstable) (2026-03-14 r89623) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang20:latest
15 [CT]  clang21  [clang21]
   R Under development (unstable) (2026-06-21 r90185) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang21:latest
16 [CT]  clang22  [clang22]
   R Under development (unstable) (2026-06-21 r90185) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/clang22:latest
17 [CT]  donttest  [donttest]
   R Under development (unstable) (2026-06-21 r90185) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/donttest:latest
18 [CT]  gcc-asan  [gcc-ASAN, gcc-UBSAN]
   R Under development (unstable) (2026-06-21 r90185) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/gcc-asan:latest
19 [CT]  gcc13  [gcc13]
   R Under development (unstable) (2026-03-15 r89629) on Fedora Linux 38 (Conta…
   ghcr.io/r-hub/containers/gcc13:latest
20 [CT]  gcc14  [gcc14]
   R Under development (unstable) (2026-03-15 r89629) on Fedora Linux 40 (Conta…
   ghcr.io/r-hub/containers/gcc14:latest
21 [CT]  gcc15  [gcc15]
   R Under development (unstable) (2026-03-15 r89629) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/gcc15:latest
22 [CT]  gcc16  [gcc16]
   R Under development (unstable) (2026-07-17 r90265) on Fedora Linux 44 (Conta…
   ghcr.io/r-hub/containers/gcc16:latest
23 [CT]  intel  [Intel]
   R Under development (unstable) (2026-02-19 r89439) on Fedora Linux 38 (Conta…
   ghcr.io/r-hub/containers/intel:latest
24 [CT]  lto  [LTO]
   R version 4.6.1 (2026-06-24) on Ubuntu 24.04.4 LTS
   ghcr.io/r-hub/containers/lto:latest
25 [CT]  mkl  [MKL]
   R Under development (unstable) (2026-07-17 r90265) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/mkl:latest
26 [CT]  nold  [noLD]
   R Under development (unstable) (2026-07-17 r90265) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/nold:latest
27 [CT]  noremap  [noRemap]
   R Under development (unstable) (2026-03-14 r89623) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/noremap:latest
28 [CT]  nosuggests  [noSuggests]
   R Under development (unstable) (2026-06-21 r90185) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/nosuggests:latest
29 [CT]  rchk  [rchk]
   R Under development (unstable) (2026-07-17 r90265) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/rchk:latest
30 [CT]  ubuntu-clang  [r-devel-linux-x86_64-debian-clang]
   R Under development (unstable) (2026-07-17 r90265) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/ubuntu-clang:latest
31 [CT]  ubuntu-gcc12  [r-devel-linux-x86_64-debian-gcc]
   R Under development (unstable) (2026-04-13 r89874) on Ubuntu 22.04.5 LTS
   ghcr.io/r-hub/containers/ubuntu-gcc12:latest
32 [CT]  ubuntu-next  [r-next, r-patched, r-patched-linux-x86_64]
   R version 4.6.1 RC (2026-06-18 r90185) on Ubuntu 24.04.4 LTS
   ghcr.io/r-hub/containers/ubuntu-next:latest
33 [CT]  ubuntu-release  [r-release, r-release-linux-x86_64, ubuntu]
   R version 4.6.1 (2026-06-24) on Ubuntu 24.04.4 LTS
   ghcr.io/r-hub/containers/ubuntu-release:latest
34 [CT]  valgrind  [valgrind]
   R Under development (unstable) (2026-07-17 r90265) on Fedora Linux 42 (Conta…
   ghcr.io/r-hub/containers/valgrind:latest
35 [CT]  vnu  [vnu]
   R version 4.6.1 (2026-06-24) on Ubuntu 24.04.4 LTS
   ghcr.io/r-hub/containers/vnu:latest

GitHub actions

  • It is also possible to use GitHub Actions to run R CMD check
  • Free for public repositories, paid service for private repositories
  • Checks will be run every time someone pushes a commit to a repository hosted on GitHub
  • Easy setup from your R console: usethis::use_github_action("check-standard")
    • This runs a standard R CMD check on three major operating systems
  • Script and documentation are developed and maintained by the r-lib organization here

GitHub

Tags

  • Tags are a feature of Git, i.e., not specific to GitHub
  • Git can tag (or “bookmark”) specific points in the code history as being important
  • Typically, for each release, create a tag vx.y.z (MAJOR.Minor.patch format)
  • The value here is that users can later check out the package in the state of this release version
    • Download in R: remotes::install_github("org/package", ref = "vx.y.z")
    • Comparison of versions are also possible, etc.

Tags: example

Releases

  • Releases are based on Git tags, and a feature of GitHub
  • Are “deployable software packages to make them available for a wider audience to download and use”
  • Contain release notes and links to the binary package files for download
    • However, for R packages these tar.gz package files are rarely used directly

Releases: example

Bioconductor

A Note on Bioconductor

  • The Bioconductor project develops, supports, and disseminates open source software for the analysis of biological assays
  • Like CRAN, Bioconductor has additional package requirements: one can only submit either to CRAN or Bioconductor
  • Packages are peer reviewed by community members
  • New packages and updates to existing packages are released semi-annually
  • Software is expected to be interoperable with other Bioconductor packages through the re-use of common data structures and infrastructure

References

Exercise

Use your project from chapter 2 :

  • Run CRAN-like checks in RStudio:
    • Go to Tools -> Project Options -> Build Tools -> “Check package - R CMD check additional options”
    • Type --as-cran
  • Alternatively, use --as-cran in argument in console:
  • Look at the CI/CD checks reported on your GitHub repository
    • Where are the R CMD check results?
  • Enable GitHub page through use_pkgdown_github_pages()
    • Note: This includes use_pkgdown(), use_github_pages(), use_github_action("pkgdown")
  • Deploy the website with pkgdown
  • Set up a GitHub action to deploy website use_github_action("pkgdown")
    • (Optional) Check the automatic GitHub page deploy action

License information