Updates developer documentation for git and devops, Re-enable testing…

… in R-CMD check for workflows (#17)

* Add macOS runner

* Only run release pipeline on new tag to main

* Update docs

* Add devops vignette

* Adds inline documentation for workflows

* Adds inline documentation for release

* Fixed os name for R cmd check

* Adding logo to readme

* Adjusting title in readme

* Fix snapshot problem

* Reorganizing website drop-downs and updating website style

* Fix version font styling

.github/workflows/Check-package.yaml

@@ -1,4 +1,5 @@
-
+# This is the primary workflow for checking the state of the package
+# It will run unittest (incl.) codecov and R CMD checks - furthermore it will check for problematic dependencies and key leakage.
 
 
 on:
@@ -12,22 +13,27 @@ on:
 name: Check Package 📦
 
 jobs:
+ # Runs dependency scan powered by oysteR - checks for known security vulnerabilities
  audit:
  name: Audit Dependencies 🕵️‍♂️
  uses: insightsengineering/r.pkg.template/.github/workflows/audit.yaml@main
 
+ # Generates a license report of package dependencies
  licenses:
  name: License Check 🃏
  uses: insightsengineering/r.pkg.template/.github/workflows/licenses.yaml@main
 
+ # Runs R CMD check using the local R-CMD-check.yaml workflow
  check:
  name: RMD check 📦
  uses: ./.github/workflows/R-CMD-check.yaml
 
+ # Runs unittests while capturing code:cov and uploads to Codecov io. See local subflow
  test:
  name: Test 🧪
  uses: ./.github/workflows/Test.yaml
 
+ # Checks for git keys etc.
  gitleaks:
  name: gitleaks 💧
  uses: insightsengineering/r.pkg.template/.github/workflows/gitleaks.yaml@main

.github/workflows/R-CMD-check.yaml

@@ -1,25 +1,25 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
-# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+# Executes R CMD check will run the check for both windows and ubuntu latest on the newest R release.
+
 on:
+ # Executable from a parent workflow.
  workflow_call:
 
 name: R-CMD-check
 
-# concurrency:
-# group: roxygen-${{ github.event.pull_request.number || github.ref }}
-# cancel-in-progress: true
-
 jobs:
  R-CMD-check:
  runs-on: ${{ matrix.config.os }}
 
  name: ${{ matrix.config.os }} (${{ matrix.config.r }})
 
+ # Setup of subjobs or here which os/R versions needs to be tested.
  strategy:
  fail-fast: false
  matrix:
  config:
  - {os: ubuntu-latest, r: 'release'}
+ - {os: windows-latest, r: 'release'}
+ - {os: macos-latest, r: 'release'}
  # - {os: ubuntu-latest, r: 'oldrel-1'}
  # - {os: ubuntu-latest, r: 'oldrel-2'}
  # - {os: ubuntu-latest, r: 'oldrel-3'}
@@ -30,25 +30,30 @@ jobs:
  R_KEEP_PKG_SOURCE: yes
 
  steps:
+ # Checkout the code
  - uses: actions/checkout@v4
 
+ # Setup pandoc which is required to built doc for pacakge
  - uses: r-lib/actions/setup-pandoc@v2
 
+ # Setup R env using the R version specified under strategy above.
  - uses: r-lib/actions/setup-r@v2
  with:
  r-version: ${{ matrix.config.r }}
- http-user-agent: ${{ matrix.config.http-user-agent }}
+ #http-user-agent: ${{ matrix.config.http-user-agent }}
  use-public-rspm: true
 
+ # Install package dependencies
  - uses: r-lib/actions/setup-r-dependencies@v2
  with:
  extra-packages: any::rcmdcheck
  needs: check
 
+ # Run the R CMD check - will upload results as an artifact.
  - uses: r-lib/actions/check-r-package@v2
  with:
- args: 'c("--no-manual", "--as-cran", "--no-tests")' # We run a secondary tests check
- # upload-snapshots: true
- # error-on: '"error"'
- # check-dir: '"check"'
- # upload-results: true
+ args: 'c("--no-manual", "--as-cran")'
+ upload-snapshots: true
+ error-on: '"error"'
+ check-dir: '"check"'
+ upload-results: true

.github/workflows/Release-package.yaml

@@ -1,21 +1,30 @@
+# Main pipeline for releasing package and documentation.
+
  on:
+ # Executes when content is pushed/merged to main or when a PR is created.
  push:
  branches: main
  pull_request:
  branches: main
+ # Can also be executed manually from Actions tab on github or as a subflow of another workflow.
  workflow_dispatch:
  workflow_call:
 
  name: Release Package 🚀
 
  jobs:
+ # Run the R-CMD check and uploads the tests incl. snaps if they fail.
+ # View subflow for details
  build:
  name: RMD Build and check
  uses: ./.github/workflows/R-CMD-check.yaml
+ # Builds the pkgdown site and deploys it on gh-pages.
+ # View subflow for details
  docs:
  needs: build
  name: Build and Deploy Docs
  uses: ./.github/workflows/pkgdown.yaml
+ # Releases the package creating a new release if on main and the push is a new tag.
  release:
  needs: [build, docs]
  name: Release

.github/workflows/Test.yaml

@@ -1,47 +1,65 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
-# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+# This is a GitHub Actions workflow file for testing an R package and reporting test coverage.
+# It is derived from examples provided by the r-lib/actions repository.
+# If you encounter build failures, you can find help at https://github.com/r-lib/actions#where-to-find-help
+
+# This workflow is triggered by a 'workflow_call' event, meaning it can be reused by other workflows.
 on:
  workflow_call:
 
+# The name of the workflow is 'test-coverage'.
 name: test-coverage
 
+# Permissions needed for the workflow to run.
 permissions:
- contents: read
- pull-requests: write
- checks: write
+ contents: read # Read access to the repository's contents.
+ pull-requests: write # Write access to pull requests to post comments, etc.
+ checks: write # Write access to checks to provide feedback on commits.
 
+# The jobs that will be run as part of this workflow.
 jobs:
  test-coverage:
+ # The job will run on the latest Ubuntu runner provided by GitHub Actions.
  runs-on: ubuntu-latest
+
+ # Environment variables that will be available to all steps in the job.
  env:
- GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+ GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} # Personal Access Token for GitHub, provided by GitHub Actions.
 
+ # The steps that will be executed as part of this job.
  steps:
+ # Check out the repository's code so that the workflow can access it.
  - uses: actions/checkout@v4
 
+ # Set up the R environment using the r-lib/actions setup-r action.
  - uses: r-lib/actions/setup-r@v2
  with:
- use-public-rspm: true
+ use-public-rspm: true # Use the public RStudio Package Manager.
 
+ # Install R package dependencies using the r-lib/actions setup-r-dependencies action.
  - uses: r-lib/actions/setup-r-dependencies@v2
  with:
- extra-packages: |
+ extra-packages: | # List of extra packages to install.
  any::covr
  any::xml2
  any::dplyr
  any::knitr
- needs: coverage
+ needs: coverage # Specify that this step needs the 'coverage' context.
 
+ # Get the name of the R package from the DESCRIPTION file and set it as an environment variable.
+ # This will be used to run the tests on the package.
  - name: Get package name
  run: |
  echo "PKGNAME=$(awk -F: '/Package:/{gsub(/[ ]+/,""); print $2}' DESCRIPTION)" >> $GITHUB_ENV
  shell: bash
 
+ # Debug step to print the package name to the console.
  - name: debug
  run: |
  echo $PKGNAME
  shell: bash
 
+ # Run the R package tests with coverage reporting using the covr package.
+ # The default test-engine for covr is not testthat so we overwrite it here by setting `type` and `code`.
  - name: Run tests with coverage
  run: |
  covr::codecov(
@@ -51,32 +69,38 @@ jobs:
  reporter = testthat::JunitReporter$new(file = file.path(normalizePath(Sys.getenv('GITHUB_WORKSPACE'), winslash = '/'), 'test-results.xml'))
  )",
  install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package"),
- clean=FALSE,
+ clean=FALSE, # Do not remove the installation path after running the tests - later steps grab files here.
  quiet=FALSE
  )
  shell: Rscript {0}
 
+ # Show the output of the testthat tests in the console for easier debugging.
  - name: Show testthat output in console
- if: always()
+ if: always() # This step will always run, regardless of previous step success/failure.
  run: |
- ## --------------------------------------------------------------------
  find '${{ runner.temp }}/package' -name 'testthat.Rout*' -exec cat '{}' \; || true
  shell: bash
 
+ # This will create a comment in the PR and add a check if the action is run on a PR.
  - name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
- if: always()
+ if: always() # This step will always run, regardless of previous step success/failure.
  with:
- files: |
+ files: | # The files containing test results to be published.
  test-results.xml
 
+ # If the tests fail, upload the test results as an artifact for further analysis.
+ # Here we include both package and test results.
  - name: Upload test results
- if: failure()
+ if: failure() # This step will only run if the previous steps have failed.
  uses: actions/upload-artifact@v4
  with:
- name: coverage-test-failures
- path: ${{ runner.temp }}/package
+ name: coverage-test-failures # Name of the artifact.
+ path: ${{ runner.temp }}/package # Path to the test results to be uploaded.
+
 
+ # Additionally we can create a coverage report and add it as a comment to the PR.
+ # Currently this reruns the tests which isn't great, but it's a start.
  - name: Create Coverage Report for comment
  run: |
  covr::package_coverage() |>
@@ -107,6 +131,7 @@ jobs:
  writeLines(con = "coverage.md")
  shell: Rscript {0}
 
+ # Add the coverage report (from previous step) as a comment to the PR.
  - name: Add Coverage PR Comment
  uses: marocchino/sticky-pull-request-comment@v2
  if: github.event_name == 'pull_request'

.github/workflows/fast-forward.yaml

@@ -1,3 +1,7 @@
+# This a small action to perform fast forward merging which is not supported by github by default.
+# NB: since this by default is run using the default GITHUB_TOKEN it will not trigger subsequent work-flows.
+# In order for this to be effective either a PAT or a github app (dependabot) should be setup 
+
 name: Fast Forward PR
 on: 
  issue_comment:

.github/workflows/pkgdown.yaml

@@ -1,15 +1,14 @@
-# Workflow adjusted from usethis::use_pkgdown_github_pages() to also publish pages from PRs in a subfolder
+# Workflow to build and deploy documentation site using GH pages.
+# For pull-request it will create a subpage under dev/#PR so that you can review changes before pulling into main.
+# NB when pulling into main it will remove previous dev/#PR sites.
 
  on:
- # push:
- # branches: [main, master]
- # pull_request:
- # branches: [main, master]
- # release:
- # types: [published]
+ # Can be triggered independently via the Actions tab
  workflow_dispatch:
+ # Can be triggered from another flow.
  workflow_call:
 
+ # By default actions can only read - Here it needs to write content (to gh_pages branch) and comments to PR.
  permissions:
  contents: write
  pull-requests: write
@@ -25,6 +24,7 @@
  env:
  GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
  steps:
+ # Checkout the repo to the runner environment
  - uses: actions/checkout@v4
 
  - uses: r-lib/actions/setup-pandoc@v2
@@ -38,12 +38,12 @@
  extra-packages: any::pkgdown, local::.
  needs: website
 
+ # Build the packagedown site.
  - name: Build site
  run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
  shell: Rscript {0}
 
  # If not pull request a brand new webpage is deployed
-
  - name: Deploy to GitHub pages 🚀
  if: github.event_name != 'pull_request'
  uses: JamesIves/github-pages-deploy-action@v4.5.0
@@ -53,7 +53,6 @@
  folder: docs
 
  # If pull request the webpage is deployed inside a dev/"PR number" folder for review
-
  - name: Add pkgdown PR Comment
  uses: marocchino/sticky-pull-request-comment@v2
  if: github.event_name == 'pull_request'