diff --git a/.github/workflows/common.yml.inactive b/.github/workflows/common.yml.inactive index 3f7ca445..ca87e5b1 100644 --- a/.github/workflows/common.yml.inactive +++ b/.github/workflows/common.yml.inactive @@ -4,6 +4,12 @@ # but can be easily used by any other R package name: Admiral Workflows +--- +# Source: https://github.com/pharmaverse/admiralci +# Common workflows designed for Admiral +# but can be easily used by any other R package +name: admiral CI/CD Workflows + on: # 'workflow_dispatch' gives you the ability # to run this workflow on demand, anytime @@ -11,29 +17,21 @@ on: # 'push' events are triggered when commits # are pushed to one of these branches push: + tags: + - "v*" branches: - main - - devel - - pre-release - - test + - patch # 'pull_request' events are triggered when PRs are # created against one of these target branches. pull_request: branches: - main - - devel - - pre-release - - test + - patch # 'release' events are triggered when... # you guessed it - when releases are made. release: types: [published] - schedule: - - cron: '21 13 * * 1,3,5' - -env: - # R version to use for the workflows - R_VERSION: "3.6" # Docs on concurrency: # https://docs.github.com/en/actions/using-jobs/using-concurrency @@ -41,102 +39,105 @@ concurrency: group: admiral-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: true +env: + R_VERSION: "release" + jobs: + get_r_version: + name: Get R version + runs-on: ubuntu-latest + outputs: + r-version: ${{ steps.get_r_version.outputs.R_VERSION }} + steps: + - name: Get R Version for Downstream Container Jobs + id: get_r_version + run: echo "R_VERSION=$R_VERSION" >> $GITHUB_OUTPUT + shell: bash style: name: Code Style uses: pharmaverse/admiralci/.github/workflows/style.yml@main if: github.event_name == 'pull_request' + needs: get_r_version with: - r-version: $R_VERSION + r-version: "${{ needs.get_r_version.outputs.r-version }}" spellcheck: name: Spelling uses: pharmaverse/admiralci/.github/workflows/spellcheck.yml@main if: github.event_name == 'pull_request' + needs: get_r_version with: - r-version: $R_VERSION + r-version: "${{ needs.get_r_version.outputs.r-version }}" readme: name: Render README uses: pharmaverse/admiralci/.github/workflows/readme-render.yml@main if: github.event_name == 'push' + needs: get_r_version with: - r-version: $R_VERSION - # This workflow autoformats the README.md file after - # it has been rendered. If you want to skip that, - # set the following value to 'true' - skip-md-formatting: false + r-version: "${{ needs.get_r_version.outputs.r-version }}" validation: name: Validation uses: pharmaverse/admiralci/.github/workflows/r-pkg-validation.yml@main if: github.event_name == 'release' + needs: get_r_version with: - r-version: $R_VERSION + r-version: "${{ needs.get_r_version.outputs.r-version }}" check: name: Check uses: pharmaverse/admiralci/.github/workflows/r-cmd-check.yml@main - if: github.event_name == 'pull_request' with: - # Control how you want the errors to manifest - # by supplying the 'error_on' parameter to - # rcmdcheck::rcmdcheck() here. - error-on: note + error-on: warning # TODO: find a way to ignore specific notes + if: github.event_name == 'pull_request' docs: name: Documentation uses: pharmaverse/admiralci/.github/workflows/pkgdown.yml@main - if: github.event_name == 'push' + if: github.event_name == 'push' || startsWith(github.ref, 'refs/tags/v') + needs: get_r_version with: - r-version: $R_VERSION - # Whether to skip multiversion docs - # Note that if you have multiple versions of docs, - # your URL links are likely to break due to path changes - skip-multiversion-docs: false - # Ref to use for the multiversion docs landing page - multiversion-docs-landing-page: main + r-version: "release" + skip-multiversion-docs: true + secrets: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} linter: name: Lint uses: pharmaverse/admiralci/.github/workflows/lintr.yml@main + needs: get_r_version if: github.event_name == 'pull_request' with: - r-version: $R_VERSION - # Set to true to lint all files each time - # the job is run on pull request - lint-all-files: false + r-version: "${{ needs.get_r_version.outputs.r-version }}" links: name: Links uses: pharmaverse/admiralci/.github/workflows/links.yml@main - if: > - github.event_name == 'push' || github.event_name == 'pull_request' + if: github.event_name == 'pull_request' coverage: name: Code Coverage uses: pharmaverse/admiralci/.github/workflows/code-coverage.yml@main if: > - github.event_name == 'push' || github.event_name == 'pull_request' + github.event_name != 'release' + needs: get_r_version with: - r-version: $R_VERSION + r-version: "${{ needs.get_r_version.outputs.r-version }}" # Whether to skip code coverage badge creation # Setting to 'false' will require you to create # an orphan branch called 'badges' in your repository skip-coverage-badges: false - templates: - name: Check Templates - uses: pharmaverse/admiralci/.github/workflows/check-templates.yml@main - if: > - github.event_name == 'push' || github.event_name == 'pull_request' - with: - r-version: $R_VERSION man-pages: name: Man Pages uses: pharmaverse/admiralci/.github/workflows/man-pages.yml@main if: github.event_name == 'pull_request' + needs: get_r_version with: - r-version: $R_VERSION - cran-status: - name: CRAN Status - uses: pharmaverse/admiralci/.github/workflows/cran-status.yml@main - if: github.event_name == 'schedule' + r-version: "${{ needs.get_r_version.outputs.r-version }}" + templates: + name: Check Templates + uses: pharmaverse/admiralci/.github/workflows/check-templates.yml@main + secrets: inherit + if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' + needs: get_r_version with: - # Whom should the issue be assigned to if errors are encountered - # in the CRAN status checks? - issue-assignees: "" - # Create an issue if one or more of the following - # statuses are reported on the check report. - status-types: "NOTE,WARNING,ERROR" + r-version: "${{ needs.get_r_version.outputs.r-version }}" + vbump: + name: Version Bump πŸ€œπŸ€› + if: github.event_name == 'push' + uses: insightsengineering/r.pkg.template/.github/workflows/version-bump.yaml@main + secrets: + REPO_GITHUB_TOKEN: ${{ secrets.PHARMAVERSE_BOT }} diff --git a/.github/workflows/pkgdown.yml b/.github/workflows/pkgdown.yml index 1baa3e0b..628ad95a 100644 --- a/.github/workflows/pkgdown.yml +++ b/.github/workflows/pkgdown.yml @@ -242,10 +242,14 @@ jobs: rlang::env_binding_lock(env = pkgdown_env) rlang::env_lock(pkgdown_env) require(desc::desc_get("Package"), character.only = TRUE) + clean = FALSE + if ("${{ inputs.skip-multiversion-docs }}" == "true"){ + clean = TRUE + } pkgdown::deploy_to_branch( new_process = FALSE, ${SUBDIR_OPTION} - clean = FALSE + clean = clean ) EOF env: diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index d19e5284..65d1baf2 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -35,7 +35,7 @@ concurrency: cancel-in-progress: true jobs: - roxygen: + spellcheck: name: Spellcheck runs-on: ubuntu-latest container: diff --git a/DESCRIPTION b/DESCRIPTION index 3fb8017e..15bddbc4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,9 +1,12 @@ Package: admiralci Type: Package -Title: ADaM in R Asset Library - CI/CD Workflows +Title: CI/CD Workflows for Admiral Version: 0.0.1 Authors@R: c( - person("Open", "Source", email = "admiralci@pharmaverse.com", role = c("aut", "cre"))) + person("Dinakar", "Kulkarni", role = c("aut")), + person("Daphne", "Grasselly", role = c("aut", "cre"), email="daphne.grasselly@roche.com"), + person("Adam", "Forys", role = c("aut")), + person("Franciszek", "Walkowiak", role = c("aut"))) Description: A set of common CI/CD workflows originally designed and developed for Admiral R package hosted in the Pharmaverse GitHub organization. License: Apache License (>= 2) diff --git a/README.Rmd b/README.Rmd index 0dc39e83..6ae1f6de 100644 --- a/README.Rmd +++ b/README.Rmd @@ -1,5 +1,5 @@ --- -title: "CI/CD Workflows for Admiral R Packages" +title: "CI/CD Workflows for Admiral R Packages" output: md_document date: '2022-08-03' --- @@ -37,161 +37,136 @@ dyn_link <- function(text, admiralci_homepage <- "https://pharmaverse.github.io/admiralci" ``` +# Purpose of admiralci +![](man/figures/admiralci_hex.png){width=60% height=60%} - -# CI/CD Workflows for Admiral R Packages - -This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are used by [`Admiral`](https://github.com/pharmaverse/admiral) and its extensions extensions. +This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are used by [`admiral`](https://github.com/pharmaverse/admiral) and its extensions. Workflows defined here are responsible for assuring high package quality standards without compromising performance, security, or reproducibility. Please refer to the [`.github/workflows`](.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`][r-lib-actions], while the installation of system dependencies and R package dependencies is managed via the [Staged Dependencies GitHub Action][sd-action]. The latter is used in conjunction with the [`staged_dependencies.yaml`](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][sd-repo]. 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. - -### [Check Templates](./.github/workflows/check-templates.yml) - -[![Check Templates](https://github.com/pharmaverse/admiralci/actions/workflows/check-templates.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/check-templates.yml) - -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. - -### [Code Coverage](./.github/workflows/code-coverage.yml) - -[![Code Coverage](https://github.com/pharmaverse/admiralci/actions/workflows/code-coverage.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/code-coverage.yml) - -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_. - -The [`covr`][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: - -``` bash -# 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 -``` - -### [Links](./.github/workflows/links.yml) +Notes : -[![Check URLs](https://github.com/pharmaverse/admiralci/actions/workflows/links.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/links.yml) +- Some workflows are using github actions from [InsightsEngineering](https://github.com/insightsengineering/) group. + +- Most of the workflows are sharing the same steps (see [Common workflows structure](https://pharmaverse.github.io/admiralci/common_structure.html)) (boilerplate code) -This workflow checks whether URLs embedded in code and documentation are valid. Invalid URLs result in workflow failures. This workflow uses [`lychee`][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 `.lycheeignore` file. -### [Lint](./.github/workflows/lintr.yml) +# Available workflows -[![Lint](https://github.com/pharmaverse/admiralci/actions/workflows/lintr.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/lintr.yml) +## Workflows triggered by Admiral MR (feature branch to main branch) -Static code analysis is performed by this workflow, which in turn uses the [`lintr`][lintr] R package. +### Check Templates -Any [`.lintr`](.lintr) configurations in the repository will be by this workflow. -### [Man Pages](./.github/workflows/man-pages.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/check-templates.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/check-templates.html")`) -[![Man Pages](https://github.com/pharmaverse/admiralci/actions/workflows/man-pages.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/man-pages.yml) +### Lintr -This workflow checks if the manual pages in the `man/` directory of the package are up-to-date with ROxygen comments in the code. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/lintr.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/lintr.html")`) -Workflow failures indicate that the manual pages are not up-to-date with ROxygen comments, and corrective actions are provided in the workflow log. +### Man Pages -### [Documentation](./.github/workflows/pkgdown.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/man-pages.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/man-pages.html")`) -[![Documentation](https://github.com/pharmaverse/admiralci/actions/workflows/pkgdown.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/pkgdown.yml) +### R CMD CHECKS -Documentation for the R package is generated via this workflow. This workflow uses the [`pkgdown`][pkgdown] framework to generate documentation in HTML, and the HTML pages are deployed to the `gh-pages` branch. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/r-cmd-check.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/r-cmd-checks.html")`) -Moreover, an additional `Versions` dropdown is generated via the [][multi-version-docs] GitHub Action, so that an end user can view multiple versions of the documentation for the package. +### Check Templates -### [Check R Versions](./.github/workflows/r-cmd-check.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/spellchecks.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/spellchecks.html")`) -[![R CMD Check](https://github.com/pharmaverse/admiralci/actions/workflows/r-cmd-check.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/r-cmd-check.yml) +### Code Coverage -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. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/code-coverage.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/code-coverage.html")`) -### [Validation](./.github/workflows/r-pkg-validation.yml) +### Readme Render -[![R Package Validation report](https://github.com/pharmaverse/admiralci/actions/workflows/r-pkg-validation.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/r-pkg-validation.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/readme-render.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/readme-render.html")`) -When a new release of the package is made, this workflow executes to create a validation report via [theValidatoR][validation]. The PDF report is then attached to the release within GitHub. +### Style -### [Render README](./.github/workflows/readme-render.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/style.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/style.html")`) -[![Render README](https://github.com/pharmaverse/admiralci/actions/workflows/readme-render.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/readme-render.yml) +## Workflows trigger by a new release -If your codebase uses a [`README.Rmd` file](README.Rmd) (like this repository), then this workflow will automatically render a `README.md` and commit it to your branch. +### Validation -### [Spelling](./.github/workflows/spellcheck.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/r-pkg-validation.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/validation.html")`) -[![Spelling](https://github.com/pharmaverse/admiralci/actions/workflows/spellcheck.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/spellcheck.yml) +### Pkgdown -Spellchecks are performed by this workflow, and the [`spelling`][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 `inst/WORDLIST`. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/pkgdown.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/pkgdown.html")`) -### [Code Style](./.github/workflows/style.yml) +## cron workflows -[![Style](https://github.com/pharmaverse/admiralci/actions/workflows/style.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/style.yml) +### Push Docker Image -Code style is enforced via the [`styler`][styler] R package. Custom style configurations, if any, will be honored by this workflow. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/push-docker-image.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/push-docker.html")`) -Failed workflows are indicative of unstyled code. +### Cran Status -### [CRAN Status](./.github/workflows/cran-status.yml) +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/cran-status.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/cran-status.html")`) -[![CRAN Status](https://github.com/pharmaverse/admiralci/actions/workflows/cran-status.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/cran-status.yml) +### Check R Tags -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. +- [Link to workflow code (yml file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/check-r-tags.yml) +- [Link to the documentation](`r paste0(admiralci_homepage, "/articles/check-r-tags.html")`) -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? +# How to use these workflows? -### Reuse (recommended) +## Reuse (recommended) 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`][workflow_call] GitHub Actions event. -The contents of the `.github/workflows/common.yml` file are available in the [`common.yml.inactive`](./.github/workflows/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 `env:` and `with:` hashes in the file for feature flags. +The contents of the `.github/workflows/common.yml` file are available in the [`common.yml.inactive`](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/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 `env:` and `with:` hashes in the file for feature flags. -### Copy as-is (not recommended) + +## Copy as-is (not recommended) Alternatively, if you want a high level of customization, you could simply copy the workflows as-is from this repository to your repository and modify them to your liking. +We do not recommand this approach. For example, you might miss some updated or even bugs fixes from `admiralci` workflows. If you need some updates in some existing workflows, please [raise an issue](https://github.com/pharmaverse/admiralci/issues). ## Where to see these workflows in action? ### Pull Request At the bottom of a pull request, you can check on the status of each workflow: - +![](man/figures/pr_workflows.jpg) ### Actions Tab -Alternatively, you can check on the workflows on the Actions tab in the repository as well: - - - -[r-lib-actions]: https://github.com/r-lib/actions -[sd-action]: https://github.com/marketplace/actions/staged-dependencies-action -[sd-repo]: https://github.com/openpharma/staged.dependencies -[lychee]: https://github.com/lycheeverse/lychee -[covr]: https://covr.r-lib.org/ -[lintr]: https://lintr.r-lib.org/ -[pkgdown]: https://pkgdown.r-lib.org/ -[multi-version-docs]: https://github.com/marketplace/actions/r-pkgdown-multi-version-docs -[validation]: https://github.com/marketplace/actions/r-package-validation-report -[spelling]: https://docs.ropensci.org/spelling/ -[styler]: https://styler.r-lib.org/ -[workflow_call]: https://docs.github.com/en/actions/using-workflows/reusing-workflows - +Alternatively, you can check on the workflows on the Actions tab in the repository as well: +![](man/figures/actions_tab_workflows.jpg) + + +Most of our workflows are using Github Marketplace actions, referenced bellow : + +- [InsightsEngineering](https://github.com/insightsengineering) +- [r-lib-actions](https://github.com/r-lib/actions) +- [sd-action](https://github.com/marketplace/actions/staged-dependencies-action) +- [sd-repo](https://github.com/openpharma/staged.dependencies) +- [lychee](https://github.com/lycheeverse/lychee) +- [covr](https://covr.r-lib.org/) +- [lintr](https://lintr.r-lib.org/) +- [pkgdown](https://pkgdown.r-lib.org/) +- [multi-version-docs](https://github.com/marketplace/actions/r-pkgdown-multi-version-docs) +- [validation](https://github.com/marketplace/actions/r-package-validation-report) +- [spelling](https://docs.ropensci.org/spelling/) +- [styler](https://styler.r-lib.org/) +- [workflow_call](https://docs.github.com/en/actions/using-workflows/reusing-workflows) \ No newline at end of file diff --git a/README.md b/README.md index c98c5aa7..639fb4a1 100644 --- a/README.md +++ b/README.md @@ -1,229 +1,151 @@ -# CI/CD Workflows for Admiral R Packages +# Purpose of admiralci + +![](man/figures/admiralci_hex.png) This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are -used by [`Admiral`](https://github.com/pharmaverse/admiral) and its -extensions extensions. Workflows defined here are responsible for -assuring high package quality standards without compromising -performance, security, or reproducibility. +used by [`admiral`](https://github.com/pharmaverse/admiral) and its +extensions. Workflows defined here are responsible for assuring high +package quality standards without compromising performance, security, or +reproducibility. Please refer to the [`.github/workflows`](.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`](https://github.com/r-lib/actions), while the -installation of system dependencies and R package dependencies is -managed via the [Staged Dependencies GitHub -Action](https://github.com/marketplace/actions/staged-dependencies-action). -The latter is used in conjunction with the -[`staged_dependencies.yaml`](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](https://github.com/openpharma/staged.dependencies). 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. - -### [Check Templates](./.github/workflows/check-templates.yml) - -[![Check -Templates](https://github.com/pharmaverse/admiralci/actions/workflows/check-templates.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/check-templates.yml) - -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. - -### [Code Coverage](./.github/workflows/code-coverage.yml) - -[![Code -Coverage](https://github.com/pharmaverse/admiralci/actions/workflows/code-coverage.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/code-coverage.yml) - -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*. - -The [`covr`](https://covr.r-lib.org/) R package is used to calculate the -coverage. - -Report summaries and badges for coverage are generated using a series of -other GitHub Actions. +Notes : -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: +* Some workflows are using github actions from + [InsightsEngineering](https://github.com/insightsengineering/) + group. + +* Most of the workflows are sharing the same steps (see [Common + workflows + structure](https://pharmaverse.github.io/admiralci/common_structure.html)) + (boilerplate code) - # 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 +# Available workflows -### [Links](./.github/workflows/links.yml) +## Workflows triggered by Admiral MR (feature branch to main branch) -[![Check -URLs](https://github.com/pharmaverse/admiralci/actions/workflows/links.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/links.yml) +### Check Templates -This workflow checks whether URLs embedded in code and documentation are -valid. Invalid URLs result in workflow failures. This workflow uses -[`lychee`](https://github.com/lycheeverse/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 -`.lycheeignore` file. +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/check-templates.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/check-templates.html) -### [Lint](./.github/workflows/lintr.yml) +### Lintr -[![Lint](https://github.com/pharmaverse/admiralci/actions/workflows/lintr.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/lintr.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/lintr.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/lintr.html) -Static code analysis is performed by this workflow, which in turn uses -the [`lintr`](https://lintr.r-lib.org/) R package. +### Man Pages -Any [`.lintr`](.lintr) configurations in the repository will be by this -workflow. +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/man-pages.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/man-pages.html) -### [Man Pages](./.github/workflows/man-pages.yml) +### R CMD CHECKS -[![Man -Pages](https://github.com/pharmaverse/admiralci/actions/workflows/man-pages.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/man-pages.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/r-cmd-check.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/r-cmd-checks.html) -This workflow checks if the manual pages in the `man/` directory of the -package are up-to-date with ROxygen comments in the code. +### Check Templates -Workflow failures indicate that the manual pages are not up-to-date with -ROxygen comments, and corrective actions are provided in the workflow -log. +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/spellchecks.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/spellchecks.html) -### [Documentation](./.github/workflows/pkgdown.yml) +### Code Coverage -[![Documentation](https://github.com/pharmaverse/admiralci/actions/workflows/pkgdown.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/pkgdown.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/code-coverage.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/code-coverage.html) -Documentation for the R package is generated via this workflow. This -workflow uses the [`pkgdown`](https://pkgdown.r-lib.org/) framework to -generate documentation in HTML, and the HTML pages are deployed to the -`gh-pages` branch. +### Readme Render -Moreover, an additional `Versions` dropdown is generated via the -[](https://github.com/marketplace/actions/r-pkgdown-multi-version-docs) -GitHub Action, so that an end user can view multiple versions of the -documentation for the package. +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/readme-render.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/readme-render.html) -### [Check R Versions](./.github/workflows/r-cmd-check.yml) +### Style -[![R CMD -Check](https://github.com/pharmaverse/admiralci/actions/workflows/r-cmd-check.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/r-cmd-check.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/style.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/style.html) -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. +## Workflows trigger by a new release -### [Validation](./.github/workflows/r-pkg-validation.yml) +### Validation -[![R Package Validation -report](https://github.com/pharmaverse/admiralci/actions/workflows/r-pkg-validation.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/r-pkg-validation.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/r-pkg-validation.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/validation.html) -When a new release of the package is made, this workflow executes to -create a validation report via -[theValidatoR](https://github.com/marketplace/actions/r-package-validation-report). -The PDF report is then attached to the release within GitHub. +### Pkgdown -### [Render README](./.github/workflows/readme-render.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/pkgdown.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/pkgdown.html) -[![Render -README](https://github.com/pharmaverse/admiralci/actions/workflows/readme-render.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/readme-render.yml) +## cron workflows -If your codebase uses a [`README.Rmd` file](README.Rmd) (like this -repository), then this workflow will automatically render a `README.md` -and commit it to your branch. +### Push Docker Image -### [Spelling](./.github/workflows/spellcheck.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/push-docker-image.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/push-docker.html) -[![Spelling](https://github.com/pharmaverse/admiralci/actions/workflows/spellcheck.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/spellcheck.yml) +### Cran Status -Spellchecks are performed by this workflow, and the -[`spelling`](https://docs.ropensci.org/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 `inst/WORDLIST`. +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/cran-status.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/cran-status.html) -### [Code Style](./.github/workflows/style.yml) +### Check R Tags -[![Style](https://github.com/pharmaverse/admiralci/actions/workflows/style.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/style.yml) +* [Link to workflow code (yml + file)](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/check-r-tags.yml) +* [Link to the + documentation](https://pharmaverse.github.io/admiralci/articles/check-r-tags.html) -Code style is enforced via the [`styler`](https://styler.r-lib.org/) R -package. Custom style configurations, if any, will be honored by this -workflow. +# How to use these workflows? -Failed workflows are indicative of unstyled code. +## Reuse (recommended) -### [CRAN Status](./.github/workflows/cran-status.yml) - -[![CRAN -Status](https://github.com/pharmaverse/admiralci/actions/workflows/cran-status.yml/badge.svg)](https://github.com/pharmaverse/admiralci/actions/workflows/cran-status.yml) - -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. - - -### [`docker image build`](./.github/workflows/push-docker-image.yml) - -This workflow is pushing a docker image inside admiralci ghcr (github container registry). It's triggered each time a change is detected inside `renv.lock` files. -A docker image is produced for each R versions (defined under `renv/profiles` folder). This image will contain every system dependencies required + `renv.lock` files packages. -This workflow mainly uses the action `insightsengineering/r-image-creator`, which is a generic action to create `rocker/rstudio` based docker images. - -## How to use these workflows? - -### Reuse (recommended) - -You could add just *one* file called `.github/workflows/common.yml` to +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`](https://docs.github.com/en/actions/using-workflows/reusing-workflows) -GitHub Actions event. +reusable via the \[`workflow_call`]\[workflow\_call] GitHub Actions +event. The contents of the `.github/workflows/common.yml` file are available in -the [`common.yml.inactive`](./.github/workflows/common.yml.inactive) +the +[`common.yml.inactive`](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/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 `env:` and `with:` hashes in the file for feature flags. -### Copy as-is (not recommended) + + +## Copy as-is (not recommended) Alternatively, if you want a high level of customization, you could simply copy the workflows as-is from this repository to your repository @@ -234,14 +156,24 @@ and modify them to your liking. ### Pull Request At the bottom of a pull request, you can check on the status of each -workflow: - +workflow: ![](man/figures/pr_workflows.jpg) ### Actions Tab Alternatively, you can check on the workflows on the Actions tab in the -repository as well: - +repository as well: ![](man/figures/actions_tab_workflows.jpg) - + +* [r-lib-actions](https://github.com/r-lib/actions) +* [sd-action](https://github.com/marketplace/actions/staged-dependencies-action) +* [sd-repo](https://github.com/openpharma/staged.dependencies) +* [lychee](https://github.com/lycheeverse/lychee) +* [covr](https://covr.r-lib.org/) +* [lintr](https://lintr.r-lib.org/) +* [pkgdown](https://pkgdown.r-lib.org/) +* [multi-version-docs](https://github.com/marketplace/actions/r-pkgdown-multi-version-docs) +* [validation](https://github.com/marketplace/actions/r-package-validation-report) +* [spelling](https://docs.ropensci.org/spelling/) +* [styler](https://styler.r-lib.org/) +* [workflow\_call](https://docs.github.com/en/actions/using-workflows/reusing-workflows) diff --git a/_pkgdown.yml b/_pkgdown.yml index a6593c6e..da9f4b5f 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,4 +1,3 @@ ---- url: https://pharmaverse.github.io/admiralci template: @@ -7,6 +6,64 @@ template: bootswatch: flatly navbar: - right: - - icon: fa-github - href: https://github.com/pharmaverse/admiralci + structure: + left: [basics, workflows_details] + right: [search, slack, newissue, github] + components: + basics: + text: Basics + menu: + - text: Common structure of the workflows + href: articles/common_structure.html + - text: Cheatsheet + href: articles/cheatsheet.html + workflows_details: + text: Workflows Details + menu: + - text: R CMD CHECKS + href: articles/r-cmd-checks.html + - text: Cran Status + href: articles/cran-status.html + - text: Code Coverage + href: articles/code-coverage.html + - text: Check Templates + href: articles/check-templates.html + - text: Links (Check broken links) + href: articles/links.html + - text: Lintr (Code lints) + href: articles/lintr.html + - text: Style (Code style) + href: articles/style.html + - text: Spellchecks + href: articles/spellchecks.html + - text: Man pages (Code Doc Rendering) + href: articles/man-pages.html + - text: Readme Render (Readme.Rmd -> Readme.md) + href: Readme.Rmd + - text: Pkgdown (build doc from Vignettes) + href: articles/pkgdown.html + - text: Tweak Pages (fix pkgdown broken links) + href: articles/tweak-page-hooks.html + - text: Pkgdown (build doc from Vignettes) + href: articles/pkgdown.html + - text: Validation (build PDF validation report) + href: articles/validation.html + - text: Push Docker Images + href: articles/push-docker.html + - text: Codespaces + href: articles/docker_and_codespaces.html + - text: Propagate (share codespaces conf) + href: articles/propagate.html + - text: Check R latest version + href: articles/check-r-tags.html + + + slack: + icon: fa-slack + href: https://app.slack.com/client/T028PB489D3/C02M8KN8269 + aria-label: Slack + newissue: + icon: fa-bug + href: https://github.com/pharmaverse/admiralci/issues/new/choose + aria-label: New Issue + diff --git a/install_devel_deps.R b/install_devel_deps.R deleted file mode 100644 index 30685669..00000000 --- a/install_devel_deps.R +++ /dev/null @@ -1,19 +0,0 @@ -# Read the dependencies from the CSV file -dependencies <- read.csv("Dependencies.list.of.docker.image.admiralci-latest.csv", - stringsAsFactors = FALSE) - -# remove built-in deps from the list -dependencies <- dependencies %>% filter(LibPath != "/usr/local/lib/R/library") - -# Loop through the dependencies and reinstall packages with specific versions -for (i in seq_len(nrow(dependencies))) { - dep_name <- dependencies[i, "Package"] - dep_version <- dependencies[i, "Version"] - version_parts <- strsplit(dep_version, "\\.")[[1]] - if (length(version_parts) == 4) { - print(sprintf("skipping installation of dep %s", dep_name)) - } else { - print(sprintf("install dependency %s - version %s", dep_name, dep_version)) - devtools::install_version(dep_name, version = dep_version, repos = "https://cran.r-project.org", force=TRUE, upgrade="always") - } -} \ No newline at end of file diff --git a/man/figures/admiralci_hex.png b/man/figures/admiralci_hex.png new file mode 100644 index 00000000..531b472d Binary files /dev/null and b/man/figures/admiralci_hex.png differ diff --git a/vignettes/assets/actions_tab_workflows.jpg b/vignettes/assets/actions_tab_workflows.jpg new file mode 100644 index 00000000..2d1d728a Binary files /dev/null and b/vignettes/assets/actions_tab_workflows.jpg differ diff --git a/vignettes/assets/cheatsheet.pdf b/vignettes/assets/cheatsheet.pdf new file mode 100644 index 00000000..97afc9ca Binary files /dev/null and b/vignettes/assets/cheatsheet.pdf differ diff --git a/vignettes/assets/cheatsheet.png b/vignettes/assets/cheatsheet.png new file mode 100644 index 00000000..e2426011 Binary files /dev/null and b/vignettes/assets/cheatsheet.png differ diff --git a/vignettes/assets/pr_workflows.jpg b/vignettes/assets/pr_workflows.jpg new file mode 100644 index 00000000..22f12ea7 Binary files /dev/null and b/vignettes/assets/pr_workflows.jpg differ diff --git a/vignettes/cheatsheet.Rmd b/vignettes/cheatsheet.Rmd new file mode 100644 index 00000000..322191c7 --- /dev/null +++ b/vignettes/cheatsheet.Rmd @@ -0,0 +1,15 @@ +--- +title: "cheatsheet" +output: + rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{cheatsheet} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +# Cheatsheet + +[![](assets/cheatsheet.png)](https://github.com/dgrassellyb/admiralci/blob/main/vignettes/assets/cheatsheet.pdf) + +(Please Download the cheatsheet to access embedded links). \ No newline at end of file diff --git a/vignettes/check-r-tags.Rmd b/vignettes/check-r-tags.Rmd new file mode 100644 index 00000000..45b6340c --- /dev/null +++ b/vignettes/check-r-tags.Rmd @@ -0,0 +1,37 @@ +--- +title: "Check R latest version" +output: + rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{CheckRTags} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +# Style Workflow + +This GitHub Actions workflow checks and enforces coding style using `styler` on R files. The workflow is triggered manually (`workflow_dispatch`) and can also be invoked as a workflow call (`workflow_call`). + +## Workflow Structure + +The workflow consists of a single job: `check-r-release`. + +### `check-r-release` Job + +This job get latest R tag (checking dockerhub container registry). This workflow is mainly here for `admiralci` developers to be warned if a new version of R is released (then a manual update of `OLD_RELEASE` env variable need to be done). +Note: If latest R tag is different from `OLD_RELEASE` this job will end-up will fail status. + +#### Inputs + +- `r-version`: The version of R to use. Default is 'release'. + +#### Steps + +1. **List rocker/rstudio tags:** Request dockerhub registry to list all available tags. Then apply regexp pattern to retrieve only tags with `^[0-9]+\.[0-9]+$` pattern, and take the highest tag. + +- `workflow_dispatch`: Manually triggered workflow with optional inputs. +- `schedule`: Run every sunday at midnight UTC. + +### Permissions + +- `contents: write`: Write permissions for repository contents. diff --git a/vignettes/check-templates.Rmd b/vignettes/check-templates.Rmd index 8c99d46f..6e647c80 100644 --- a/vignettes/check-templates.Rmd +++ b/vignettes/check-templates.Rmd @@ -56,8 +56,9 @@ These steps handle staged dependencies, including cache restoration and running 6. **Restore cache**: Restores the cache for staged dependencies. 7. **Run Staged dependencies**: Runs the staged dependencies action. +8. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) #### Install and Run Templates -8. **Install package**: Builds and installs the R package. -9. **Run Template Scripts**: Reads the package description, identifies template scripts, and executes them. If any script fails, the workflow stops and provides an error message. +9. **Install package**: Builds and installs the R package. +10. **Run Template Scripts**: Reads the package description, identifies template scripts, and executes them. If any script fails, the workflow stops and provides an error message. diff --git a/vignettes/code-coverage.Rmd b/vignettes/code-coverage.Rmd index 01991284..61312f74 100644 --- a/vignettes/code-coverage.Rmd +++ b/vignettes/code-coverage.Rmd @@ -11,6 +11,28 @@ vignette: > # Code Coverage Workflow This GitHub Actions workflow is designed for testing and generating code coverage reports for an R package. It uses a matrix strategy to test different versions of R and includes options to skip code coverage badge creation. +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_. + +The [`covr`][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: + +``` bash +# 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 +``` ## Inputs @@ -60,22 +82,23 @@ This job verifies templates in the R package. It runs on a docker container inst 5. **Restore cache**: Restores the cache for staged dependencies. 6. **Setup Pandoc**: Sets up Pandoc for documentation rendering. 7. **Run Staged dependencies**: Runs the staged dependencies action. +8. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) #### Run Coverage -8. **Run coverage**: Runs code coverage tests, generates coverage reports, and outputs the coverage percentage. +9. **Run coverage**: Runs code coverage tests, generates coverage reports, and outputs the coverage percentage. #### Check Coverage Reports -9. **Check whether coverage reports exist**: Checks for the existence of coverage reports. +10. **Check whether coverage reports exist**: Checks for the existence of coverage reports. -10. **Set coverage percentage as output**: Sets the coverage percentage as an output variable. +11. **Set coverage percentage as output**: Sets the coverage percentage as an output variable. -11. **Generate Coverage Summary Report**: Generates a coverage summary report, adds badges, and uploads the report for review. +12. **Generate Coverage Summary Report**: Generates a coverage summary report, adds badges, and uploads the report for review. #### Add Coverage PR Comment -12. **Add Coverage PR Comment**: Adds a comment to the pull request with the coverage summary. +13. **Add Coverage PR Comment**: Adds a comment to the pull request with the coverage summary. ## Job: `badge` diff --git a/vignettes/common_structure.Rmd b/vignettes/common_structure.Rmd index 9fe348b4..998cc7f5 100644 --- a/vignettes/common_structure.Rmd +++ b/vignettes/common_structure.Rmd @@ -12,37 +12,44 @@ vignette: > ## R-version input -For most of the workflows, we need to select a specific R version to load the associated `renv` profile. -That's why most of the actions have a `r-version` input (by default set-up to `4.1`) : +For most of the workflows, we need to select a specific R version. +That's why most of the actions have a `r-version` input: ``` inputs: r-version: - description: 'The version of R to use' - default: '4.1' - required: false - type: string + description: 'The version of R to use' + default: 'release' + required: false + type: choice + options: + - devel + - oldrel ``` +By default, we have `r-version=release`, and users can also use `devel` and `latest` versions. + +- `release` means we are using latest stable version of `R`. +- `oldrel` means we are using previous release of R (for example if current release is `4.4`, oldrel will be `4.3`). +- `devel` refers to the development version of R, which contains the latest changes and features that are still under development. This version is typically used by developers who want to test new features. The "devel" version may be less stable. + ## Use of `admiralci` docker images Once the `r-version` is picked, the worfklows will run inside a docker container instance. Indeed, `admiralci` contains an action `push-docker-image`, to be able to build `rocker:rstudio` images -for each available versions of `R` (versions specified in `renv/profiles`, see [renv profiles conf](get_started.html#renv-profiles-configuration-handling-several-r-versions)). -At the building step of these docker images, every dependencies specified in the `renv.lock` files are installed. -A total of 4 images are created : -- `admiralci-4.1` -- `admiralci-4.2` -- `admiralci-4.3` +for each available version of `R` : + +- `admiralci-oldrelease` +- `admiralci-release` - `admiralci-devel` -These images and store them in admiralci ghcr (Github Container Registry - Place to store docker images), and are then reused to execute the workflows in docker container instances like this : +These images are stored in admiralci ghcr (Github Container Registry - Place to store docker images), and are then reused to execute the workflows in docker container instances like this : ``` container: image: "ghcr.io/pharmaverse/admiralci-${{ inputs.r-version }}:latest" ``` -(More more details on docker images creation process and how they're used, please read [Docker images and codespaces](docker_and_codespaces.html)) section. +(For more details on docker images creation process, please read [Push Docker Images](push-docker.html)) workflow documentation). ## Checkout repository @@ -55,7 +62,8 @@ This action is used to checkout on the right repository. This is a step commonly ## Staged dependencies -The staged dependencies action allow to install every necessary upstream dependencies for `admiral` package, suche as : +The staged dependencies action allow to install every necessary upstream dependencies for `admiral` package, such as : + - `pharmaversesdtm` (SDTM test data) - `admiraldev` (utilities functions for the Admiral package family) diff --git a/vignettes/cran-status.Rmd b/vignettes/cran-status.Rmd index c910db51..a5af02d8 100644 --- a/vignettes/cran-status.Rmd +++ b/vignettes/cran-status.Rmd @@ -1,9 +1,9 @@ --- -title: "Cran Status" +title: "CRAN Status" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Cran Status} + %\VignetteIndexEntry{CRAN Status} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -11,7 +11,7 @@ vignette: > # CRAN Status Workflow This GitHub Actions workflow checks the CRAN status of an R package. It can create an issue if specified statuses ('NOTE', 'WARN', 'ERROR') are reported on the check report. -Note : this workflow is using [insightEngineering Cran Status Monitor](https://github.com/insightsengineering/cran-status-monitor) action. +Note : this workflow is using [insightsEngineering Cran Status Monitor](https://github.com/insightsengineering/cran-status-monitor) action. ## Inputs diff --git a/vignettes/docker_and_codespaces.Rmd b/vignettes/docker_and_codespaces.Rmd index dc80e54f..d7c841ad 100644 --- a/vignettes/docker_and_codespaces.Rmd +++ b/vignettes/docker_and_codespaces.Rmd @@ -17,6 +17,8 @@ knitr::opts_chunk$set( ) ``` +WARNING: this article is outdated (codespaces need to be re-designed since we decided to stop handling dependencies with renv) - WIP + # Introduction This article will go over the following: @@ -129,7 +131,7 @@ knitr::include_graphics("./assets/prebuild_ready.png", dpi = 144) ### Propagation -Each time a change is detected inside .devcontainer folder, the [propagation job](./.github/workflows/propagate.yml) will be trigger (see doc [lock_and_prop](lock_and_prop.html)) +Each time a change is detected inside .devcontainer folder, the [propagation job](./.github/workflows/propagate.yml) will be triggered. ### Improvement ideas diff --git a/vignettes/get_started.Rmd b/vignettes/get_started.Rmd deleted file mode 100644 index 98cfb2ef..00000000 --- a/vignettes/get_started.Rmd +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Get Started" -output: - rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Get Started} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -# Purpose of admiralci - -This repository contains GitHub Actions continuous integration/continuous delivery (CI/CD) workflows, most of which are used by [`Admiral`](https://github.com/pharmaverse/admiral) and its extensions. -Workflows defined here are responsible for assuring high package quality standards without compromising performance, security, or reproducibility. - -Please refer to the [`.github/workflows`](.github/workflows) directory to view the source code for the GitHub Actions workflows. - -Notes : - -- Some workflows are using github actions from [InsightEngineering](https://github.com/insightsengineering/) group. - -- Most of the workflows are sharing the same steps (see [Common workflows structure](common_structure.html)) (boilerplate code) - - -# Available workflows - -## Workflows trigger by Admiral MR (feature branch to main branch) - -- [check-templates.yml](check-templates.html) -- [links.yml](links.html) -- [man-pages.yml](man-pages.html) -- [r-cmd-check.yml](r-cmd-checks.html) -- [spellcheck.yml](spellchecks.html) -- [code-coverage.yml](code-coverage.html) -- [lintr.yml](lintr.html) -- [readme-render.yml](readme-render.html) -- [style.yml](style.html) - -## Workflows trigger by a new release - -- [r-pkg-validation.yml](validation.html) -- [pkgdown.yml](pkgdown.html) - -## Workflows to manage dependencies change (`renv.lock` files changes) - -Before talking about workflows, let's first explain how dependencies are handled in `Admiral` package. -The developpers are using `renv` framework, to be able to use the same versions between developpers. - -### renv profiles configuration (Handling several R versions) - -#### renv folder content - -The admiral project is built to be compatible with several R-versions (for now `4.1`, `4.2`, `4.3` and also latest development version of R (`devel` version)). - -``` -renv -β”œβ”€β”€ profiles -β”‚ β”œβ”€β”€ 4.1 -β”‚ β”œβ”€β”€ renv.lock -β”‚ β”œβ”€β”€ 4.2 -β”‚ β”œβ”€β”€ renv.lock -β”‚ β”œβ”€β”€ 4.3 -β”‚ β”œβ”€β”€ renv.lock -``` - -The activation of the proper `renv.lock` file is managed inside the `.Rprofile` file. (The code implemented in `.Rprofile` is implemented at each new R session). - -#### Structure of `.Rprofile file` file : - -- `.get_dependencies` function : - -This function is defined to determine the dependencies for the renv (R package manager) snapshot. -It looks for the "admiral" DESCRIPTION file and extracts its dependencies, looking for suggested packages in the current project. - -- Then there is a step to look for current R version on a admiral devlopper environment, and load the proper R profile (use of the associate `renv.lock` file) -- Then the variable `RENV_AUTOLOADER_ENABLED` is enabled or not depending on the context (if it's run through github workflows, it will be disabled, to preserve pre-installed dependencies on the workflows - more details on this in [Docker and Codespaces](docker_and_codespaces.html)) - - - -### Workflows to manage `renv` environment - -#### Automatic updates of `renv` environment - -2 workflows has been defined to do following steps : - -- automatically update the `renv.lock` file content. -- propagate the `renv.lock` file changes to every `admiral` packages (`admiral`, `admiralonco` ..). - -This [Lock updates and Propagation](lock-and-prop.html) section explains this in details. -And you can find more details here about these 2 workflows (technical details) : - -- [r-renv-lock.yml](renv-lock.html) -- [propagate.yml](propagate.html) - -#### Docker images updates (`admiralci` container registry images) - -## cron workflows - -- [push-docker-image.yml](push-docker.html) (to update the `devel` image only) -- [cran-status.yml](cran-status.html) diff --git a/vignettes/links.Rmd b/vignettes/links.Rmd index cfc94490..3a5071f1 100644 --- a/vignettes/links.Rmd +++ b/vignettes/links.Rmd @@ -10,15 +10,15 @@ vignette: > # Check URLs Workflow -This GitHub Actions workflow checks URLs in documentation files. It runs on the main, devel, and pre-release branches for push events and specified pull request events. +This GitHub Actions workflow checks URLs in documentation files. It runs on the main, and pre-release branches for push events and specified pull request events. ## Workflow Triggers This workflow is triggered in the following ways: -1. **Push Events**: Triggered on pushes to the main, devel, and pre-release branches. +1. **Push Events**: Triggered on pushes to the main, and pre-release branches. -2. **Pull Request Events**: Triggered on pull requests when opened, synchronized, reopened, or ready for review for the main, devel, and pre-release branches. +2. **Pull Request Events**: Triggered on pull requests when opened, synchronized, reopened, or ready for review for the main, and pre-release branches. 3. **Manual Dispatch**: You can manually trigger the workflow using the "workflow_dispatch" event. @@ -48,3 +48,5 @@ This job validates URLs in documentation files. It runs on Ubuntu 20.04. - **Environment Variables**: - `GITHUB_TOKEN`: GitHub token for authentication. + +Note: It's possible to ignore some links checks using `.lycheeignore` file. diff --git a/vignettes/lintr.Rmd b/vignettes/lintr.Rmd index 8df15c65..f2015f61 100644 --- a/vignettes/lintr.Rmd +++ b/vignettes/lintr.Rmd @@ -62,12 +62,24 @@ This job performs linting tasks. 6. **Run Staged dependencies**: Runs staged dependencies action to set up the environment. -7. **Install latest release of lintr**: Installs the latest release of lintr from the CRAN repository if specified. +7. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) -8. **Install package**: Installs the R package locally if specified. +8. **Install latest release of lintr**: Installs the latest release of lintr from the CRAN repository if specified. -9. **Changed files**: Gets the list of changed files using the Ana06/get-changed-files action. +9. **Install package**: Installs the R package locally if specified. -10. **Lint**: Performs linting using lintr on the R package. Excludes files based on the changed files list. +10. **Changed files**: Gets the list of changed files using the Ana06/get-changed-files action. -11. **Error if lints are detected**: Raises an error if lints are detected, prompting a review and adjustment of the code. \ No newline at end of file +11. **Lint**: Performs linting using lintr on the R package. Excludes files based on the changed files list. + +12. **Error if lints are detected**: Raises an error if lints are detected, prompting a review and adjustment of the code. + +Note : a `.lintr` file can be configured at the upstream repository level, to be able for example to exclude some lint rules such as this example : + +``` +exclusions: list( + "R/data.R" = Inf, + "inst" = list(undesirable_function_linter = Inf), + "vignettes" = list(undesirable_function_linter = Inf) + ) +``` \ No newline at end of file diff --git a/vignettes/lock_and_prop.Rmd b/vignettes/lock_and_prop.Rmd deleted file mode 100644 index a53ad6a9..00000000 --- a/vignettes/lock_and_prop.Rmd +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Lock File Updates and Propagation" -output: - rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{Lock File Updates and Propagation} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r setup, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -# Introduction - -This article will go over the following: - -* The process for requesting an update to the Lock Files, i.e. `renv.lock`, for the `{admiral}` family of packages. -* How `{admiralci}` uses a propagation process to update `renv.lock` files across the family of `{admiral}` packages. - -## Updates to Lock Files - -The intention of the `renv.lock` file is to create a harmonized development environment across our many different companies and collaborators. The core team feels that if everyone is working with the same version of R and the same versions of R packages then communication around development issues will be much easier. - -Unfortunately, this adoption of a `renv.lock` file also creates a few barriers for our development process. First, if we **lock** in a version of R and R packages then we can not quickly adopt the latest and greatest of updates from new releases. Second, how does a team decide to update a certain package or version of R and who gets to make that final call? Finally, when do we make updates to the lock file. Hopefully, the below will provide some guidance around these issues. Please note, these process might change over time and admiral developers are encouraged to stay up to date with the latest processes and participate in the discussion. - -**Note:** Through GitHub Actions we continuously test admiral's integration with the latest 3 snapshots of dependent R packages on CRAN that are closest in date to latest 3 versions of R. Please see [GitHub Actions/Workflows]( https://pharmaverse.github.io/admiraldev/articles/pr_review_guidance.html#github-actionsworkflows) on the `{admiraldev}` site for more information on this process. - -### R Package Updates and Lock Files - -As you gathered, package updates to the `renv.lock` file are permissible and needed as our family grows and dependent packages and R versions change over time. - -Most of the scenarios for updates can be slotted into the following: - -1. A new function in a dependent package, e.g. `{dplyr}` is available and could be utilized in a new admiral function. -2. A new package is available with new functions that could greatly simplify our code base or add in additional functionality. -3. A breaking bug is discovered in a dependent package that breaks backward compatibility for that package with `{admiral}`. -4. A dependency is no longer used in `{admiral}`. -5. A dependency package cause an issue in R checks or R-CMD checks to fail . - -The first step for requesting an update for a R package in the `renv.lock` file is to raise it in our [slack channel](https://app.slack.com/client/T028PB489D3/C028SJ83KM1). The next step is to make an issue for it in the [admiralci repository](https://github.com/pharmaverse/admiralci/) and tag `{admiral}` leads. This will create discussion around why this update is needed. The `admiralci` leads will then make the final decision (**almost always in the affirmative**) and we can move this to the attention of other admiral extension package leads. Once all leads are aware of this needed update, then the `renv.lock` file for the entire admiral family packages will be updated through a **centrally controlled propagation processes**. It is expected that all repositories adopt this update `renv.lock` file. - -## Propagation Process - -Through GitHub Actions we have developed the ability to **propagate** updated lock files with our preferred versions of R and R packages throughout the family of admiral packages. This ensures that developers working on `{pharmaversesdtm}` and `{admiralonco}` have the same common environment as those working on `{admiraldev}` and `{admiralvaccines}`. - - -The file that does the propagation process is called [`propagate.yml`](https://github.com/pharmaverse/admiralci/blob/main/.github/workflows/propagate.yml) located in the `.github/workflows` folder of the [admiralci repository](https://github.com/pharmaverse/admiralci/). - -The process is implemented to generate `renv.lock` file automatically. It will be done for all supported R releases that need to be compatible with admiral. The propagation occurs in the following steps: - -1. The modification of `r-renv-lock.yml` triggers regenerate the package dependencies that automatically commit changes for `renv.lock`. -2. A Pull Request will be created in all admiral family repos as seen below with the tile **Propagate renv.lock from pharmaverse/admiralci** title. -3. A `pharmaverse-bot` is the author of the Pull Request as seen in `[2]` in the image below. -4. The bot assign relevant reviewers to the Pull Requests. The reviewers tend to be admins or core contributors to the repo and can be adjusted if needed. - -**Note:** In `[1]` you will see that one reviewer has a special shield symbol next to their name. This person is a codeowner of the `common.yml` and is alerted whenever a change is made to this file. You can read more about codeowners on [About Code Owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) in GitHub Documentation - -Note that this propagate process also propagate .devcontainer files which are configuration files for codespaces (see [Codespaces](codespaces.html)) - -```{r, echo = FALSE} -knitr::include_graphics("./assets/prop.png", dpi = 144) -``` - - -### R Version Updates and Lock Files - -Currently, the family of admiral packages operate 3 R versions back from the latest R version release. For example, if the latest release of R is `4.2`, then our `renv.lock` files will use `4.0.5`. We use `4.0.5` as this has the latest patches available for `4.0`. We will use the propagation process to update the latest version of R when a new release becomes available. - -It's possible to use R version `4.1` and `4.2` with the renv profiles. The profiles are used to reproduce the development environment. Please notice that the profiles for R `4.1` and `4.2` using different cran snapshot. The snapshot is generated by discovering the packages used by `admiral` packages, with extra rules for missing dependencies. The script is defining minimum version or specific version of packages. For example, we can define `roxygen2` version that is used across all other packages to generate documentation. - -**Note:** Through GitHub Actions we continuously test admiral's integration with the latest three version of R and closest snapshot of R packages to the R version release date. For example, while we use version `4.0.5` in development we are continuously testing R version `4.1` and `4.2` for compatibility with `admiral`. - -# Working with project profiles - -The automate generation create the `renv.lock` file for all supported R version by admiral project. The use of profiles simplifies the testing process across all R environments. - -To activate a particular profile, use: - -```r -renv::activate(profile = "4.1") -``` - -The available profiles are: - -- R 4.1 - Currently the default development profile. -- R 4.2 - Generated for R 4.2. -- R 4.3 - Generated for R 4.3. - -You can read more about profiles in [renv documentation](https://rstudio.github.io/renv/articles/profiles.html). - -# Containers - -Several `admiral` developers are looking into a container strategy to be utilized in a parallel with the `renv.lock` strategy. - - -We are keen on continuously evaluating this process as we balance our software development and stability needs. Please don't hesitate to raise concerns or questions around this process, but at this point in time we have determined this is our best course to maintain a consistent development environment across multiple repository, companies and collaborations. - - diff --git a/vignettes/man-pages.Rmd b/vignettes/man-pages.Rmd index 1ccb60ee..32b5f480 100644 --- a/vignettes/man-pages.Rmd +++ b/vignettes/man-pages.Rmd @@ -50,10 +50,11 @@ This job runs Roxygen to generate and check man pages in the R package. It runs 5. **Restore cache**: Restores the cache for staged dependencies. 6. **Run Staged dependencies**: Runs the staged dependencies action. +7. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) #### Roxygen Workflow -7. **Generate man pages**: Runs `roxygen2::roxygenize()` to generate man pages. -8. **Set-up safe dir**: Sets up a safe directory for git configuration. -9. **Roxygen check**: Checks if manuals are up-to-date with Roxygen comments and provides guidance if differences are found. If differences are found, the workflow will fail, giving the cmd to run to the admiral devs : +8. **Generate man pages**: Runs `roxygen2::roxygenize()` to generate man pages. +9. **Set-up safe dir**: Sets up a safe directory for git configuration. +10. **Roxygen check**: Checks if manuals are up-to-date with Roxygen comments and provides guidance if differences are found. If differences are found, the workflow will fail, giving the cmd to run to the admiral devs : `roxygen2::roxygenize('.', roclets = c('rd', 'collate', 'namespace'))` \ No newline at end of file diff --git a/vignettes/pkgdown.Rmd b/vignettes/pkgdown.Rmd index 94ee8652..76274de8 100644 --- a/vignettes/pkgdown.Rmd +++ b/vignettes/pkgdown.Rmd @@ -11,7 +11,7 @@ vignette: > # pkgdown Workflow This GitHub Actions workflow automates the generation and deployment of documentation for an R package using `pkgdown`. The workflow supports multiple versions and offers flexibility in customization. -This workflow use rmarkdown to be able to generate html documentation from `Rmd` files (vignettes folder). This documentation is then stored in `gh-pages` branch (an orphan branch) and published. +This workflow uses rmarkdown to be able to generate html documentation from `Rmd` files (vignettes folder). This documentation is then stored in `gh-pages` branch (an orphan branch) and published. Note : this workflow is using [InsightEngineering pkgdown multiversion action](https://github.com/insightsengineering/r-pkgdown-multiversion) action. ## Inputs @@ -25,7 +25,7 @@ Note : this workflow is using [InsightEngineering pkgdown multiversion action](h - `skip-multiversion-docs`: Skip the creation of multi-version docs. Default: false. If set to True, a subfolder will be created under `gh-pages` (with the current github reference (branch/tag) name) - `multiversion-docs-landing-page`: Ref to use for the multiversion docs landing page. Default: main. - `latest-tag-alt-name`: An alternate name to use for 'latest-tag' for multiversion pkgdown docs. Default: "". -- `branches-or-tags-to-list`: Regular expression defining branches or tags listed under the 'Versions' dropdown menu. Default: ^main$|^devel$|^pre-release$|^latest-tag$|^cran-release$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$. +- `branches-or-tags-to-list`: Regular expression defining branches or tags listed under the 'Versions' dropdown menu. Default: `^main$|^devel$|^pre-release$|^latest-tag$|^cran-release$|^develop$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$`. ## Workflow Structure diff --git a/vignettes/propagate.Rmd b/vignettes/propagate.Rmd index ca4d8dcf..fbf94196 100644 --- a/vignettes/propagate.Rmd +++ b/vignettes/propagate.Rmd @@ -8,21 +8,11 @@ vignette: > %\VignetteEncoding{UTF-8} --- -# Propagate renv.lock, Rprofile, and .devcontainer Files Workflow +WARNING: this article mention codespaces configuration. The Admiral codespaces feature is still in progress, and current codespaces article is outdated for now. -This GitHub Actions workflow is specific to the admiralci project. It is designed to propagate changes in `renv.lock`, `.Rprofile`, and `.devcontainer` (for codespaces configuration) to multiple repositories within the project. +# Propagate .devcontainer Files Workflow -## Workflow Structure - -The workflow consists of two jobs: `integrity` and `propagation`. - -### `integrity` Job - -This job checks the integrity of the `renv.lock` file and performs diagnostics to ensure consistency with the R environment. It is triggered on pull requests targeting the `main` branch and when run manually. - -### `propagation` Job - -This job propagates changes in `renv.lock`, `.Rprofile`, and `.devcontainer` files to specified repositories within the admiralci project. It is triggered on pull requests targeting the `main` branch and when run manually. This job is dependent on the successful completion of the `integrity` job. +This GitHub Actions workflow is specific to the admiralci project. It is designed to propagate changes in `.devcontainer` files (for codespaces configuration) to multiple repositories within the project. ## Inputs @@ -31,30 +21,17 @@ This job propagates changes in `renv.lock`, `.Rprofile`, and `.devcontainer` fil - `pull_request`: Triggered on pull requests targeting the `main` branch and specific file paths. - `workflow_dispatch`: Allows manual triggering of the workflow. -## Jobs - -### `integrity` Job - -#### Steps - -1. **Checkout repo:** Retrieves the repository for the current workflow run. -2. **Get R version from renv.lock file:** Extracts the R version from the `renv.lock` file. -3. **Setup R:** Sets up the R environment based on the extracted R version. -4. **Run renv.lock diagnostics:** Installs the `renv` package and performs diagnostics on the R environment. - -### `propagation` Job - -#### Steps +### Steps 1. **Checkout this repo:** Checks out the current repository. 2. **Checkout specified repository:** Checks out the specified repository based on the matrix configuration. -3. **Update files in the specified repository:** Updates `renv.lock`, `.Rprofile`, and `.devcontainer` files in the specified repository. +3. **Update files in the specified repository:** Updates `.devcontainer` files in the specified repository. 4. **Commit and push changes:** Commits the changes and pushes them to the repository. 5. **Create Pull Request:** Creates a pull request in the specified repository, assigning reviewers. ### Matrix Configuration -The `propagation` job uses a matrix strategy to iterate over specified repositories with different configurations. (MR with new `renv.lock`/`.Rprofile`/`.devcontainer` files will be created for each element of the matrix, with associated `reviewers` field) +The `propagation` job uses a matrix strategy to iterate over specified repositories with different configurations. (MR with new `.devcontainer` file will be created for each element of the matrix, with associated `reviewers` field) ```yaml repos: @@ -64,4 +41,4 @@ repos: - name: admiraldev target-branch: main reviewers: bms63, cicdguy - # Add more repositories as needed +``` diff --git a/vignettes/push-docker.Rmd b/vignettes/push-docker.Rmd index f52fb871..b716e526 100644 --- a/vignettes/push-docker.Rmd +++ b/vignettes/push-docker.Rmd @@ -10,60 +10,69 @@ vignette: > # Deploy Docker Image Workflow -This GitHub Actions workflow automates the deployment of Docker images based on changes in the `renv.lock` file within the `renv/profiles` directory. It is designed to run on pushes to the `main` branch, manual triggers, and on a schedule (every day at midnight UTC on Wednesdays and Sundays). -Note : this workflow is using [InsightEngineering R image creator action](https://github.com/insightsengineering/r-image-creator). +This GitHub Actions workflow automates the deployment of Docker images based on changes in the `DESCRIPTION` file. It is designed to run on pushes to the `main` branch, manual triggers, and on a schedule (every day at midnight UTC on Wednesdays and Sundays). +Note : this workflow is using [InsightsEngineering R image creator action](https://github.com/insightsengineering/r-image-creator). + +## Matrix + +- R versions are specified in the matrix for parallel execution. + +``` +matrix: + r_version: ['release', 'devel', 'oldrel'] +``` ## Workflow Structure -The workflow consists of three jobs: `get_renv_list`, `deploy-image`, `deploy-image-devel`, and `store_deps`. +The workflow consists of three jobs: `get_old_release`, `deploy-image`, and `store_deps`. -### `get_renv_list` Job +### `get_old_release` Job -This job determines the list of `renv.lock` files that need updates based on the changed files in the `renv/profiles` directory. It differentiates between scheduled runs and manual/dispatch runs. -(For scheduled runs, only `devel` image will be created - see [devel image](#deploy-devel-image-job) section) +This job retrieve the R version corresponding to "oldrelease". It contains only a simple step parsing `OLD_RELEASE` env variable. This variable is set up manually + (checking actual release version of R and taking the previous version). Another workflow (with cron workflow) is running in admiralci to check if a new release of R is available (this allow admiralci developers to check if they need to update `OLD_RELEASE` variable). #### Steps -1. **Checkout repo:** Retrieves the repository for the current workflow run. -2. **Get changed files in renv/profiles:** Determines the changed `renv.lock` files. -3. **Get Updated renv:** Decides whether to update all Docker images or only modified `renv.lock` versions. +1. **get old release:** Retrieves value of env variable `OLD_RELEASE`, and store it in `$GITHUB_OUTPUT` variables. ### `deploy-image` Job -This job deploys Docker images based on the specified configurations. +This job deploys Docker images based on the specified configurations. By the end of this job, the following images will be created and stored in admiralci ghcr (github container registry) : + +- admiralci-release +- admiralci-devel +- admiralci-oldrel + +The images are available in [admiralci ghcr](https://github.com/orgs/pharmaverse/packages?repo_name=admiralci). #### Steps 1. **Checkout repo:** Checks out the current repository. -2. **Print message:** Displays a message indicating the Docker image update. 3. **Set image specs:** Retrieves package name, R version, and other specifications. -4. **Call deploy docker image action:** Invokes the Docker image deployment action for each R version and associated `renv.lock` file. +4. **Call deploy docker image action:** Invokes the Docker image deployment action for each R version. -### `deploy-image-devel` Job - -This job deploys the development version of Docker images. (based on `rstudio/rocker:devel` images using development version of R). -For this job, we do not use `renv` lock files, but directly install dependencies from `DESCRIPTION` file with `devtools`. - -#### Steps - -1. **Call deploy docker image action devel:** Invokes the Docker image deployment action for the development version. ### `store_deps` Job -This job stores dependencies of `devel` image into a CSV file. (for now this CSV file is stored inside the action artifacts, but this should be moved to docker images releases artifacts) +This job create admiralci release artifacts, for each docker image () #### Steps -1. **Store deps into CSV file:** Retrieves installed packages on `devel` image, and stores them in a CSV file. +1. **Store deps into CSV file:** Retrieves installed packages for each image, and stores them in a CSV file. 2. **Upload deps.csv artifact:** Uploads the CSV file containing dependencies as an artifact. +3. **Delete current release existing artifacts** Delete admiralci existing release artifacts (this is necessary before the step bellow) +4. **Upload SBOM to release πŸ”Ό** Upload admiralci release artifacts + +The output artifacts are available in [`admiralci` latest release](https://github.com/pharmaverse/admiralci/releases/tag/latest). These artifacts allow developers to retrieve versions of installed dependencies in the workflows, to ensure reproducibility locally. +But note that dependencies artifacts are also produced during [R CMD CHECKS](r-cmd-checks.html) workflow. ## Inputs ### Triggers -- `push`: Triggered on pushes to the `main` branch with changes in `renv/profiles/**/renv.lock`. +- `push`: Triggered on pushes to the `main` branch with changes in `DESCRIPTION`. - `workflow_dispatch`: Allows manual triggering of the workflow. -- `schedule`: Runs every day at midnight UTC on Wednesdays and Sundays. (for `devel` image only) +- `schedule`: Runs every day at midnight UTC on Wednesdays and Sundays. ## Permissions diff --git a/vignettes/r-cmd-checks.Rmd b/vignettes/r-cmd-checks.Rmd index d5b281c4..f931401e 100644 --- a/vignettes/r-cmd-checks.Rmd +++ b/vignettes/r-cmd-checks.Rmd @@ -11,7 +11,7 @@ vignette: > # R CMD Check Workflow -This GitHub Actions workflow performs R CMD checks on specified R versions and repositories. The checks are triggered by manual dispatch, pushes to the `main` or `devel` branches, and pull requests targeting these branches. +This GitHub Actions workflow performs R CMD checks on specified R versions and repositories. The checks are triggered by manual dispatch, pushes to the `main` branch, and pull requests targeting this branch. ## Workflow Structure @@ -19,7 +19,9 @@ The workflow consists of a single job: `R-CMD-check`. ### `R-CMD-check` Job -This job runs R CMD checks on different R versions, leveraging specified CRAN repositories. The job is conditioned not to run if the commit message contains '[skip r-cmd-check]'. The checks are performed in parallel for each specified R version, using [Matrix Strategy](#matrix) +This job runs R CMD checks on different R versions, leveraging specified CRAN repositories. The job is conditioned not to run if the commit message contains '[skip r-cmd-check]'. +The checks are performed in parallel for each specified R version, using [Matrix Strategy](#matrix). +Artifacts are also produced for each R version from the matrix (`renv.lock` and `deps.csv`). Developers can download these artifacts in the Action summary page to be able to ensure reproducibility (having exactly the same dependencies versions locally). #### Inputs @@ -32,9 +34,12 @@ This job runs R CMD checks on different R versions, leveraging specified CRAN re 2. **Checkout repo:** Checks out the repository based on the event type (push or pull request). 3. **Restore cache:** Restores cached dependencies. 4. **Run Staged dependencies:** Executes staged dependencies action. -5. **Check Version:** Determines if the package has a maintenance version. -6. **Check:** Performs R CMD checks using `rcmdcheck::rcmdcheck()`. -7. **Upload check results:** Uploads check results as an artifact in case of failure. +5. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) +6. **Upload dependencies artifacts:** Create `renv.lock` and `deps.csv` file (containing docker image dependencies) +7. **Upload deps.csv and renv.lock artifacts:** Upload `renv.lock` and `deps.csv` files as artifacts. +8. **Check Version:** Determines if the package has a maintenance version. +9. **Check:** Performs R CMD checks using `rcmdcheck::rcmdcheck()`. +10. **Upload check results:** Uploads check results as an artifact in case of failure. ### Concurrency @@ -46,21 +51,17 @@ Concurrency settings are specified to manage concurrent workflow runs effectivel - `workflow_dispatch`: Allows manual triggering of the workflow. - `workflow_call`: Triggered by a workflow call event. -- `push`: Triggered on pushes to the `main` or `devel` branches. -- `pull_request`: Triggered on pull requests targeting the `main` or `devel` branches. +- `push`: Triggered on pushes to the `main` branch. +- `pull_request`: Triggered on pull requests targeting the `main` branch. ### Matrix - The workflow runs on admiralci docker images (depending on the matrix element r version). -- R versions and CRAN repositories are specified in the matrix for parallel execution. +- R versions are specified in the matrix for parallel execution. ``` matrix: - config: - - {r: '4.1', repos: 'https://packagemanager.posit.co/cran/2021-05-03/'} - - {r: '4.2', repos: 'https://packagemanager.posit.co/cran/2022-01-03/'} - - {r: '4.3', repos: 'https://packagemanager.posit.co/cran/__linux__/focal/latest'} - - {r: 'devel', repos: 'https://packagemanager.posit.co/cran/__linux__/focal/latest'} + r_version: ['release', 'devel', 'oldrel'] ``` Note: We will change soon the `repos` element to use CRAN repo (https://cran.r-project.org/) @@ -68,3 +69,5 @@ Note: We will change soon the `repos` element to use CRAN repo (https://cran.r-p ## Permissions - `write-all`: Provides write permissions for various operations. + +Note: It's possible to ignore some folders/files during build process, using `.Rbuildignore` file. diff --git a/vignettes/readme-render.Rmd b/vignettes/readme-render.Rmd index 191caa9d..7e3d9d56 100644 --- a/vignettes/readme-render.Rmd +++ b/vignettes/readme-render.Rmd @@ -22,7 +22,7 @@ This job renders the README from R Markdown to Markdown and optionally formats t #### Inputs -- `r-version`: The version of R to use. Default is '4.1'. +- `r-version`: The version of R to use. Default is 'release'. - `skip-md-formatting`: Skip markdown auto-formatting. Default is 'false'. #### Steps @@ -33,9 +33,10 @@ This job renders the README from R Markdown to Markdown and optionally formats t 4. **Normalize inputs:** Normalizes the R version input. 5. **Restore cache:** Restores cached dependencies. 6. **Run Staged dependencies:** Runs staged dependencies action. -7. **Render README to markdown:** Renders `README.Rmd` to `README.md`. -8. **Install Markdown formatter:** Installs the Markdown formatter if not skipping formatting. -9. **Commit and push formatted README.md:** Commits and pushes changes to the formatted README.md file. +7. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) +8. **Render README to markdown:** Renders `README.Rmd` to `README.md`. +9. **Install Markdown formatter:** Installs the Markdown formatter if not skipping formatting. +10. **Commit and push formatted README.md:** Commits and pushes changes to the formatted README.md file. ### Triggers diff --git a/vignettes/renv-lock.Rmd b/vignettes/renv-lock.Rmd deleted file mode 100644 index 8c6e8861..00000000 --- a/vignettes/renv-lock.Rmd +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "renv.lock" -output: - rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{renv.lock} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -# R Renv Lock Generation Workflow - -This GitHub Actions workflow generates the `renv.lock` file for R packages. It is triggered on pull requests targeting the main branch, specifically on changes to the `.github/workflows/r-renv-lock.yml` file. - -## Workflow Structure - -The workflow consists of a single job: `r-renv-lock-gen`. - -### `r-renv-lock-gen` Job - -This job generates the `renv.lock` file for different R versions and operating systems. - -#### Inputs - -- `os`: The operating system for the job. Currently set to 'ubuntu-20.04'. -- `r`: The R version to use. Available versions are '4.1', '4.2', '4.3'. -- `repos`: The CRAN repository to use. - -#### Steps - -1. **Get branch names:** Extracts branch names. -2. **Checkout repo:** Checks out the repository based on the event type (pull request). -3. **Setup R:** Sets up the specified R version. -4. **Install system dependencies:** Installs required system dependencies. -5. **Collect dependencies:** Generates the `renv.lock` file based on the specified R version and the DESCRIPTION file. -6. **Commit and push changes:** Commits and pushes changes to the repository. - -### Triggers - -- `pull_request`: Triggered on pull requests targeting the main branch with changes to the `.github/workflows/r-renv-lock.yml` file. - -### Concurrency - -Concurrency settings are applied to prevent parallel execution for the same pull request or branch. - -## Permissions - -- `contents: write`: Write permissions for repository contents. - -Note : This action is quite hard to maintain, there are indeed some automation parts, such as `get_dependencies` function to configure `renv` snapshot with the `DESCRIPTION` file (taking also Suggests deps). -But some dependencies constraints have to be fixed manually, calling `install_min_version` function to install a dependency with minimal version constraint. diff --git a/vignettes/spellchecks.Rmd b/vignettes/spellchecks.Rmd index 32460532..ce1e11f3 100644 --- a/vignettes/spellchecks.Rmd +++ b/vignettes/spellchecks.Rmd @@ -14,15 +14,15 @@ This GitHub Actions workflow performs spellchecking on the specified R files. Th ## Workflow Structure -The workflow consists of a single job: `roxygen`. +The workflow consists of a single job: `spellcheck`. -### `roxygen` Job +### `spellcheck` Job This job runs spellcheck on R files. #### Inputs -- `r-version`: The version of R to use. Default is '4.1'. +- `r-version`: The version of R to use. Default is 'release'. - `exclude`: List of paths to exclude (comma-separated list). Default is an empty string. #### Conditions @@ -36,7 +36,8 @@ The spellcheck job is skipped if the commit message contains `[skip spellcheck]` 3. **Checkout repository:** Checks out the repository for events other than pull requests. 4. **Restore cache:** Restores cached dependencies. 5. **Run Staged dependencies:** Runs staged dependencies action. -6. **Run Spellcheck:** Executes the spellcheck action on specified R files. +6. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) +7. **Run Spellcheck:** Executes the spellcheck action on specified R files. ### Triggers @@ -46,3 +47,6 @@ The spellcheck job is skipped if the commit message contains `[skip spellcheck]` ### Permissions - `contents: write`: Write permissions for repository contents. + + +Note : It's possible to ignore some spell checks using `inst/WORDLIST` file. It's possible to update it automatically using directly `spelling::update_wordlist()` diff --git a/vignettes/style.Rmd b/vignettes/style.Rmd index ef152ab8..e08e75c2 100644 --- a/vignettes/style.Rmd +++ b/vignettes/style.Rmd @@ -22,7 +22,7 @@ This job performs code style checks and enforces styling using `styler`. #### Inputs -- `r-version`: The version of R to use. Default is '4.1'. +- `r-version`: The version of R to use. Default is 'release'. #### Conditions @@ -36,8 +36,9 @@ The style check job is skipped if the commit message contains `[skip style]`. 4. **Normalize inputs:** Normalizes the R version input. 5. **Restore cache:** Restores cached dependencies. 6. **Run Staged dependencies:** Runs staged dependencies action. -7. **Get changed files:** Retrieves the list of changed files, excluding renv files. -8. **Run styler:** Applies `styler` to the changed R files and checks for style violations. If violations are found, the workflow displays relevant information and version details (files with style violation will be displayed using `git diff` after running styler on the workflows) +7. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) +8. **Get changed files:** Retrieves the list of changed files. +9. **Run styler:** Applies `styler` to the changed R files and checks for style violations. If violations are found, the workflow displays relevant information and version details (files with style violation will be displayed using `git diff` after running styler on the workflows) ### Triggers @@ -47,3 +48,5 @@ The style check job is skipped if the commit message contains `[skip style]`. ### Permissions - `contents: write`: Write permissions for repository contents. + +Note: It's possible to fix locally style issues using `styler::style_file()`. diff --git a/vignettes/validation.Rmd b/vignettes/validation.Rmd index 47880780..d36e745a 100644 --- a/vignettes/validation.Rmd +++ b/vignettes/validation.Rmd @@ -1,9 +1,9 @@ --- -title: "Spell Checks" +title: "Validation Report" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Spell Checks} + %\VignetteIndexEntry{Validation Report} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -20,10 +20,11 @@ The workflow consists of a single job: `r-pkg-validation`. ### `r-pkg-validation` Job This job generates a validation report for a specified version of R. The report is built using `thevalidatoR` action and uploaded to the release upon success. +The PDF report is then attached to the release within GitHub. #### Inputs -- `r-version`: The version of R to use. Defaults to '4.1' and accepts choices '4.1', '4.2', '4.3'. +- `r-version`: The version of R to use. Defaults to 'release'. #### Steps @@ -32,8 +33,9 @@ This job generates a validation report for a specified version of R. The report 3. **Normalize inputs:** Normalizes the input R version, defaulting to '4.1' if not specified. 4. **Restore cache:** Restores cached dependencies. 5. **Run Staged dependencies:** Executes staged dependencies action. -6. **Build report:** Uses `thevalidatoR` action to build the validation report. -7. **Upload report to release:** Uploads the validation report to the release if the job is successful. +6. **Install dependencies from DESCRIPTION:** install dependencies from DESCRIPTION (in case of missing dependencies in parent admiralci docker image) +7. **Build report:** Uses `thevalidatoR` action to build the validation report. +8. **Upload report to release:** Uploads the validation report to the release if the job is successful. ### Triggers