This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are used by
Admiral and its extensions extensions. Workflows defined here are responsible for assuring high package quality standards without compromising performance, security, or reproducibility.
Please refer to the
.github/workflows directory to view the source code for the GitHub Actions workflows.
What these workflows do?
Most workflows have a
BEGIN boilderplate steps and
END boilderplate steps section within them which define some standard steps required for installing system dependencies, R version and R packages which serve as dependencies for the package.
The underlying mechanisms for installing R and Pandoc are defined in
r-lib/actions, while the installation of system dependencies and R package dependencies is managed via the Staged Dependencies GitHub Action. The latter is used in conjunction with the
staged_dependencies.yaml file in order to install dependencies that are in the same stage of development as the current package. You can read more about how it works here. Note that the latter is not necessary for this workflow to work and is completely optional.
Following the installation of system dependencies, R, and package dependencies, each workflow does something different.
This workflow checks for issues within template scripts. For example, in admiral package there are several template scripts with admiral-based functions showing how to build certain ADaM datasets. As we update the admiral functions, we want to make sure these template scripts execute appropriately. Functions in the template scripts that are deprecated or used inappropriately will cause this workflow to fail.
This workflow measures code coverage for unit tests and reports the code coverage as a percentage of the total number of lines covered by unit tests vs. the total number of lines in the codebase.
covr R package is used to calculate the coverage.
Report summaries and badges for coverage are generated using a series of other GitHub Actions.
For this workflow to execute successfully, you will need to create an orphan branch called
badges in your GitHub repository. You can do that using the following steps:
# Create orphan branch git checkout --orphan badges # Back up files mv .git /tmp/.git-backup # Remove everything else rm -rf * .* # Restore git files mv /tmp/.git-backup .git # Create a README file echo "# Badges" > README.md # Add, commit and push your new branch git add . && git commit -m "Init badges" && git push origin badges
This workflow checks whether URLs embedded in code and documentation are valid. Invalid URLs result in workflow failures. This workflow uses
lychee to detect broken links. Occasionally this check will detect false positives of urls that look like urls. To remedy, please add this false positive to the
Static code analysis is performed by this workflow, which in turn uses the
lintr R package.
.lintr configurations in the repository will be by this workflow.
This workflow checks if the manual pages in the
man/ directory of the package are up-to-date with ROxygen comments in the code.
Workflow failures indicate that the manual pages are not up-to-date with ROxygen comments, and corrective actions are provided in the workflow log.
Documentation for the R package is generated via this workflow. This workflow uses the
pkgdown framework to generate documentation in HTML, and the HTML pages are deployed to the
Moreover, an additional
Versions dropdown is generated via the GitHub Action, so that an end user can view multiple versions of the documentation for the package.
Check R Versions
This workflow performs
R CMD check for the package. Failed workflows are typically indicative of problems encountered during the check, and therefore an indication that the package does not meet quality standards.
When a new release of the package is made, this workflow executes to create a validation report via theValidatoR. The PDF report is then attached to the release within GitHub.
If your codebase uses a
README.Rmd file (like this repository), then this workflow will automatically render a
README.md and commit it to your branch.
Spellchecks are performed by this workflow, and the
spelling R package is used to detect spelling mistakes. Failed workflows typically indicate misspelled words. In the
inst/WORDLIST file, you can add words and or acronyms that you want the spell check to ignore, for example CDISC is not an English word but a common acronym used within Pharma. The workflow will flag this until a user adds it to the
Code style is enforced via the
styler R package. Custom style configurations, if any, will be honored by this workflow.
Failed workflows are indicative of unstyled code.
This workflow allows you to monitor the current status of checks on CRAN, if your package has been published on CRAN. Given that CRAN has its own systems on which it runs checks and it might not be possible to emulate all of their checks using GitHub Actions or CI/CD, it’s just more efficient to let their systems run tests and be notified via a GitHub issue if an error is encountered.
Usually CRAN sends out email notifications if errors are encountered during their checks but only individual package owners are notified and a stringent deadline of 2 weeks is given to remediate the errors on CRAN. To mitigate the risk of the package being kicked off CRAN, this workflow provides transparency and visibility to all project collaborators by creating a GitHub issue so that the errors can be remediated before the deadline has passed.
How to use these workflows?
You could add just one file called
.github/workflows/common.yml to directly import these workflows while receiving the latest updates and enhancements, given that the workflows defined in this repository are reusable via the
workflow_call GitHub Actions event.
The contents of the
.github/workflows/common.yml file are available in the
common.yml.inactive file in this repository. Feature flags in the form of
workflow_call inputs are available for customization purposes. Feature flags are documented in the same file - look for the
with: hashes in the file for feature flags.