thevalidatoR

An R Package Validation Report
- Description
- Action Type
- Author
- Inputs
- Outputs
- How to use
- Quickstart
- V1.0 Examples
  - rbmi
  - admiral

An R Package Validation Report

Description

A Github Action that generates a validation report for an R package. The four main steps are:

Run R CMD check (check installation)
Run covr::package_coverage() (check unit test coverage)
Run covtracer (link documentation to unit tests)
Place results into report
If valtools present - run valtools and also publish report? (to discuss)
Attach report as object to release

Action Type

Composite

Author

Roche

Inputs

report_pkg_dir:

Description: Path to package's root

Required: false

Default: .
report_template_path:

Description: File path of the R markdown template to use for the report. The default template is available here.

Required: false

Default: template.Rmd
report_rmarkdown_format:

Description: The output format to use when rendering the report. Value is used by rmarkdown::render's output_format parameter.

Required: false

Default: pdf_document
report_output_prefix:

Description: The output filename prefix for the validation report. If left blank, it defaults to the following convention: <package name>-<package version>-validation-report.

Required: false

Default: ""
additional_tlmgr_packages:

Description: Additional tex packages to install with tlmgr.

Required: false

Default: courier ec
no_cache:

Description: Disable github action R dependency caching.

Required: false

Default: false
cache_version:

Description: Version of the cache. To clean cache bump this version.

Required: false

Default: v1
disable_install_dev_deps:

Description: Disable installation of dev dependencies while building the report.

Required: false

Default: false

Outputs

report_output_filename:

Description: Filename of the generated report.

How to use

To use this GitHub Action you will need to complete the following:

Create a new file in your repository called .github/workflows/r-pkg-validation.yml
Copy the template over (and edit if you wish to modify it)

Quickstart

In your repository you should have a .github/workflows/validatoR.yml file with GitHub Action similar to below:

---
name: R Package Validation report

on: # Run this action when a release is published
  release:
    types: [published]

jobs:
  r-pkg-validation:
    name: Create report 📃
    runs-on: ubuntu-latest
    container:
      image: rocker/verse:4.1.1
    # Set Github token permissions
    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
    permissions:
      contents: write
      packages: write
      deployments: write
    steps:
      - name: Checkout repo 🛎
        uses: actions/checkout@v3

      - name: Build report 🏗
        id: validation
        uses: insightsengineering/thevalidatoR@main
        # see parameters above for custom templates and other formats

      # Upload the validation report to the release
      - name: Upload report to release 🔼
        if: success()
        uses: svenstaro/upload-release-action@v2
        with:
          file: ${{ steps.validation.outputs.report_output_filename }}
          asset_name: ${{ steps.validation.outputs.report_output_filename }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref }}
          overwrite: false

V1.0 Examples

rbmi

You can see an example report from rbmi, using the first version of this gh-action, here.

This was built as a test on a fork of the original rbmi package. When we created a release in that fork, this PDF was automatically built and added to the release as can be seen below.

And you can see the gh-action action that was triggered by the release being published. Note that it must install the package, run tests and construct the metrics needed by cov-tracer and covr, which in the case of rbmi a computationally heavy package - took quite a while!

admiral

You can see an example report from admiral, using the first version of this gh-action, here.

pharmaR / thevalidatoR

readme