thevalidatoR

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

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
• 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.qmd

• 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

None

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.4.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@v4

      - name: Build report 🏗
        id: validation
        uses: insightsengineering/thevalidatoR@v2
        # 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: ./validation_report.pdf
          asset_name: validation-report.pdf
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          tag: ${{ github.ref }}
          overwrite: true

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.