¶ Authors: Brian Schilder, Alan Murphy, Nathan Skene ¶

¶ README updated: Jan-09-2023 ¶

Intro

GitHub Actions are a powerful way to automatically launch workflows every time you push changes to a GitHub repository. This is a form of Continuous Integration (CI), which helps ensure that your code is always working as expected (without having to manually check each time).

Here, we have designed a robust, reusable, and flexible action specifically for the development of R packages. We also provide an R function to automatically generate a workflow file that calls the rworkflows composite action:

Currently, rworkflows action performs the following tasks:

Builds a Docker container to run subsequent steps within.
Builds and checks your R package (with CRAN and/or Bioconductor checks).
Runs units tests.
Runs code coverage tests and uploads the results to Codecov.
(Re)builds and launches a documentation website for your R package.
Pushes an Rstudio Docker container to DockerHub with your R package and all its dependencies pre-installed.

Importantly, these workflow files and action are designed to work with any R package out-of-the-box. This means you won’t have to manually edit any yaml files, just run the rworkflows::use_workflow() function and you’re ready to go!

Quickstart

Install and create the workflow in your R package’s project folder.

## in R
if(!require("rworkflows")) remotes::install_github("neurogenomics/rworkflows")
path <- rworkflows::use_workflow()

Push to GitHub, and let everything else run automatically!

## in the Terminal
git add .
git commit -m "Added GHA workflow via rworkflows::use_workflow()"
git push

Documentation

Get started

Introductory tutorial for using rworkflows.

GitHub Secrets

Before pushing changes to your new R package, you will need to set up one or more GitHub Secrets:

PAT_GITHUB [Required]: Speeds up installations and gives access to private repos on GitHub Actions. You can generate your very own Personal Authentication Token using these instructions.
DOCKER_TOKEN [Optional]: Allows GitHub Actions to push to a DockerHub account.

Docker/Singularity

Copy-and-paste instructions for creating a Docker or Singularity container with the rworkflows R package pre-installed.

Dependency graph

Interactive graph showing all the GitHub repos that currently use the rworkflows action.

Citation

If you use rworkflows, please cite:

Brian M. Schilder, Alan E. Murphy, & Nathan G. Skene (2023) The rworkflows suite: automated continuous integration for quality checking, documentation website creation, and containerised deployment of R packages, Research Square; https://doi.org/10.21203/rs.3.rs-2399015/v1

Acknowledgments

rworkflows builds upon the work of many others, especially the following:

`biocthis`

This workflow is derived from the workflow generated by the use_bioc_github_action() function within the biothis package.

Key changes in `rworkflows`

Uses dynamic variables to specify R/Bioconductor versions (e.g. r: "latest") and the name of your R package, as opposed to static names that are likely to become outdated (e.g. r: "4.0.1").
Additional error handling and dependencies checks.
Re-renders README.Rmd before rebuilding the documentation website.

`actions/`

A general set of GitHub Actions.

`r-lib/actions`

A set of GitHub Actions for R development.

`JamesIves/github-pages-deploy-action`

Builds and deploys the GitHub Pages documentation website in the rworkflows GHA workflows.

`docker/build-push-action`

A set of GitHub Actions for building/pushing Docker containers.

`bioconductor_docker`

Uses the official bioconductor/bioconductor_docker Docker container.

NOTE: Whenever a new version of Bioconductor is released, the bioconductor/bioconductor_docker container will often lag behind the actual Bioconductor releases for up to several days, due to the time it takes to update the container. This means that sometimes “devel” in Bioconductor/bioconductor_docker is actually referring to the current “release” version of Bioconductor (i.e. the previous Bioc version’s “devel”). For further details, see this Issue, and the Bioconductor release schedule.

`scFlow`

This DockerFile was partly adapted from the scFlow Dockerfile.

Unlike other Dockerfiles, this one does not require any manual editing when applying to different R packages. This means that users who are unfamiliar with Docker do not have to troubleshoot making this file correctly. It also means that it will continue to work even if your R package dependencies change.

`act`

A very useful command line tool for testing GitHub Actions locally.

Session Info

utils::sessionInfo()

## R version 4.2.1 (2022-06-23)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur ... 10.16
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## loaded via a namespace (and not attached):
##  [1] BiocManager_1.30.19 compiler_4.2.1      pillar_1.8.1       
##  [4] RColorBrewer_1.1-3  yulab.utils_0.0.6   tools_4.2.1        
##  [7] digest_0.6.31       jsonlite_1.8.4      evaluate_0.19      
## [10] lifecycle_1.0.3     tibble_3.1.8        gtable_0.3.1       
## [13] pkgconfig_2.0.3     rlang_1.0.6         cli_3.5.0          
## [16] DBI_1.1.3           rstudioapi_0.14     rvcheck_0.2.1      
## [19] yaml_2.3.6          xfun_0.36           fastmap_1.1.0      
## [22] stringr_1.5.0       dplyr_1.0.10        knitr_1.41         
## [25] desc_1.4.2          generics_0.1.3      vctrs_0.5.1        
## [28] dlstats_0.1.6       rprojroot_2.0.3     grid_4.2.1         
## [31] tidyselect_1.2.0    here_1.0.1          glue_1.6.2         
## [34] R6_2.5.1            fansi_1.0.3         rmarkdown_2.19     
## [37] ggplot2_3.4.0       badger_0.2.2        magrittr_2.0.3     
## [40] scales_1.2.1        htmltools_0.5.4     rworkflows_0.99.5  
## [43] assertthat_0.2.1    colorspace_2.0-3    utf8_1.2.2         
## [46] stringi_1.7.8       munsell_0.5.0