From df83f7f91b17472f3e6df16bce43987f2d2c6f20 Mon Sep 17 00:00:00 2001 From: Levi Waldron Date: Wed, 21 Oct 2026 12:24:51 -0400 Subject: [PATCH 1/2] Simplify docs and rename to Rapid BiocCheck Workflow - Remove stale workflow_comparison.md (diff against old waldronlab workflow) - Fix broken anchors in the workflow generator help text - Move versioning/release checklist to technical_notes.md; fix locations - Drop unused pages/id-token permissions from canary.yml - Add badge instructions to README Quick Start Co-Authored-By: Claude --- .github/copilot-instructions.md | 2 +- .github/workflows/bioccheck.yml | 6 +- .github/workflows/canary.yml | 3 - README.md | 10 +- bioccheck_usage.md | 49 ++-- docs/adr/0001-dynamic-container-tagging.md | 2 +- docs/index.html | 10 +- technical_notes.md | 23 +- workflow_comparison.md | 322 --------------------- 9 files changed, 44 insertions(+), 383 deletions(-) delete mode 100644 workflow_comparison.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b12a9d7..9356e39 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -15,4 +15,4 @@ You are an expert in GitHub Actions and R/Bioconductor continuous integration. W 1. **Opt-in Architecture**: Core functionality must work with zero configuration. Any features requiring elevated repository permissions (e.g., `pages: write`) or external secrets (e.g., `CODECOV_TOKEN`) must be disabled by default and explicitly opted into via boolean inputs (see ADR 0005). 2. **Workflow Generator Synchronization**: Any changes made to `bioccheck.yml` inputs, secrets, or permissions MUST be mirrored in **both** the JavaScript object logic inside `docs/index.html` and the "Workflow Inputs & Parameters" reference table in `bioccheck_usage.md`. If a new feature requires repository-level setup (e.g., adding a secret), those instructions must be added to `bioccheck_usage.md` and linked directly from the option's help text in `docs/index.html` to prevent synchronization drift (see ADR 0007). 3. **Architecture Decision Records (ADRs)**: Any significant structural change or new design pattern in these reusable workflows should be documented with a new ADR in `docs/adr/` using the Nygard format. -4. **Release & Version Tag Synchronization**: Whenever changing the default workflow version reference (e.g. from `@main` to `@v1` or incrementing version tags), you MUST update all 4 reference locations in lockstep: `ci.yml`, `docs/index.html` (`workflowObj.jobs.bioccheck.uses`), `README.md`, and `bioccheck_usage.md`. See `technical_notes.md` for the full release checklist. +4. **Release & Version Tag Synchronization**: Whenever changing the default workflow version reference (e.g. from `@main` to `@v1` or incrementing version tags), you MUST update all 3 reference locations in lockstep: `ci.yml`, `docs/index.html` (`workflowObj.jobs.bioccheck.uses`), and `technical_notes.md` (Versioning Strategy). See `technical_notes.md` for the full release checklist. diff --git a/.github/workflows/bioccheck.yml b/.github/workflows/bioccheck.yml index f28b72f..166bae6 100644 --- a/.github/workflows/bioccheck.yml +++ b/.github/workflows/bioccheck.yml @@ -1,4 +1,4 @@ -name: Bioc Container Check +name: Rapid BiocCheck Workflow on: workflow_call: @@ -53,7 +53,7 @@ jobs: fi # Derive the container tag from the branch name. - # Valid ghcr.io/bioconductor/bioconductor_docker tags: devel, RELEASE_X_Y + # Valid bioconductor/bioconductor_docker tags: devel, RELEASE_X_Y if [[ "${REF_NAME}" =~ ^RELEASE_ ]]; then DOCKER_TAG="${REF_NAME}" elif [[ "${REF_NAME}" == "devel" || "${REF_NAME}" == "master" || "${REF_NAME}" == "main" ]]; then @@ -115,6 +115,7 @@ jobs: uses: actions/cache@v6 with: path: /usr/local/lib/R/site-library + # The "-1-" segment is a manual cache version; bump it to discard all existing caches. key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }} restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1- @@ -204,7 +205,6 @@ jobs: with: path: docs - # Note: Inherits permissions from caller. Caller must grant 'pages: write' and 'id-token: write' when enable_pkgdown is true. deploy: needs: - check diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml index 55820ac..30d3b12 100644 --- a/.github/workflows/canary.yml +++ b/.github/workflows/canary.yml @@ -13,9 +13,6 @@ on: jobs: canary: - permissions: - pages: write - id-token: write uses: ./.github/workflows/bioccheck.yml with: error_on: 'never' diff --git a/README.md b/README.md index 8cec2c8..6c64040 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,13 @@ [![Canary Check](https://github.com/bioconductor/workflows/actions/workflows/canary.yml/badge.svg)](https://github.com/bioconductor/workflows/actions/workflows/canary.yml) [![pages-build-deployment](https://github.com/bioconductor/workflows/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/bioconductor/workflows/actions/workflows/pages/pages-build-deployment) -This repository (`bioconductor/workflows`) hosts reusable GitHub Actions workflows for R/Bioconductor package development. - +This repository (`bioconductor/workflows`) hosts the **Rapid BiocCheck Workflow**, a reusable GitHub Actions workflow for R/Bioconductor package development. **NOTE**: This is pre-release. Please try it and file issues, but some things may not work yet. The first stable release will be tagged `v1`. ## Quick Start -To run the Linux version of the "official" Bioconductor `R CMD check` and `BiocCheck`, just copy [ci.yml](ci.yml) template to `.github/workflows/ci.yml` in your package repository on GitHub. It should "just work" and will automatically check against the right Bioconductor version based on the name of the branch that is changed or targeted by a pull request (e.g. RELEASE_X_Y checks against that release; devel/main/anything else checks against devel). +To run `R CMD check` and `BiocCheck` in the official Bioconductor Linux container, just copy [ci.yml](ci.yml) template to `.github/workflows/ci.yml` in your package repository on GitHub. It should "just work" and will automatically check against the right Bioconductor version based on the name of the branch that is changed or targeted by a pull request (e.g. RELEASE_X_Y checks against that release; devel/main/anything else checks against devel). To show the check status at the top of your package's `README.md`, add this badge, replacing `` with your GitHub organization or username and `` with your repository name: @@ -33,6 +32,5 @@ For Multi-OS (Linux, macOS, Windows, WebAssembly) checks, use the [r-universe-or The documentation for these workflows has been separated into distinct files for clarity: -- [**BiocCheck Usage**](bioccheck_usage.md): Comprehensive instructions for using the `bioccheck.yml` reusable workflow, including test coverage and `pkgdown` setup. -- [**Workflow Comparison**](workflow_comparison.md): A detailed comparison of this workflow vs r-universe to help you choose the right one for your needs. -- [**Technical Notes**](technical_notes.md): Software architecture, ADRs, internal test flows (`canary.yml`, `actionlint.yml`), and guidelines for contributors. +- [**BiocCheck Usage**](bioccheck_usage.md): Instructions for using the `bioccheck.yml` reusable workflow, including test coverage, `cyclocomp`, `pkgdown` setup, and status badges. +- [**Technical Notes**](technical_notes.md): Software architecture, ADRs, internal test workflows (`canary.yml`, `actionlint.yml`), versioning, and guidelines for contributors. diff --git a/bioccheck_usage.md b/bioccheck_usage.md index 4d270dd..c1c4bbe 100644 --- a/bioccheck_usage.md +++ b/bioccheck_usage.md @@ -1,16 +1,17 @@ -# Rapid Feedback Container Check (`bioconductor/bioccheck` workflow) +# Rapid BiocCheck Workflow (`bioccheck.yml`) -The **Container Check** workflow runs `R CMD check` and `BiocCheck` inside the official `bioconductor/bioconductor_docker` Linux container. Because system libraries and R dependencies are pre-installed in the container, this workflow runs rapidly and is ideal for PRs and continuous commits. It tests *only* on Linux and *only* against one version of Bioconductor that is determined dynamically from the name of the branch that is being tested directly or by Pull Request. This is sufficient for most development and many Bioconductor package maintainers. +The **Rapid BiocCheck Workflow** runs `R CMD check` and `BiocCheck` inside the official `bioconductor/bioconductor_docker` Linux container. Because system libraries and R dependencies are pre-installed in the container, it runs quickly and is ideal for PRs and continuous commits. It tests *only* on Linux and *only* against one version of Bioconductor, chosen from the branch name. This is sufficient for most development and many Bioconductor package maintainers. -## Key Features -* **Dynamic Container Matching**: The container is chosen from the *target* branch of a pull request, or from the branch that was pushed. - * `RELEASE_X_Y` uses `bioconductor/bioconductor_docker:RELEASE_X_Y`. - * `devel`, `main`, and `master` use `bioconductor/bioconductor_docker:devel`. - * Any other branch name uses `devel` and logs a warning. For a pull request, the branch the PR comes from does not matter: a PR from `my-fix` into `RELEASE_3_20` uses `RELEASE_3_20`. For a push, a feature branch cut from a release branch still gets `devel`. - * To use a different container, set the `bioc_version` input (e.g. `RELEASE_3_20`). It overrides the branch name. -* **R Dependency Caching**: Caches R package dependencies in `/usr/local/lib/R/site-library` keyed on `depends.Rds` and R version. -* **Integrated Checks**: Executes `R CMD check` (configurable error threshold via `error_on`) and `BiocCheck` (with `quit-with-status = TRUE`). -* **Optional Features**: Test coverage reporting via Codecov, cyclomatic complexity analysis via `cyclocomp`, and `pkgdown` site build/deployment. +## How the Container Is Chosen + +The container is chosen from the *target* branch of a pull request, or from the branch that was pushed. + +* `RELEASE_X_Y` uses `bioconductor/bioconductor_docker:RELEASE_X_Y`. +* `devel`, `main`, and `master` use `bioconductor/bioconductor_docker:devel`. +* Any other branch name uses `devel` and logs a warning. For a pull request, the branch the PR comes from does not matter: a PR from `my-fix` into `RELEASE_3_20` uses `RELEASE_3_20`. For a push, a feature branch cut from a release branch still gets `devel`. +* To use a different container, set the `bioc_version` input (e.g. `RELEASE_3_20`). It overrides the branch name. + +R package dependencies are cached between runs, keyed on the package's dependency list and the R version. ## Usage @@ -24,7 +25,7 @@ To add additional features like `COVR` and `pkgdown`, or change error sensitivit Even if you use the Workflow Generator, you must perform these one-time repository settings to use optional features: -**For Codecov:** +**For Codecov** (coverage is uploaded on pushes and PRs to non-release branches only): 1. **Obtain Codecov Token**: Log in to [Codecov](https://about.codecov.io/), link your repository, and copy the repository upload token. 2. **Set Repository Secret**: In your GitHub repository, navigate to **Settings** → **Secrets and variables** → **Actions** → **New repository secret**. Create a secret named `CODECOV_TOKEN` containing your token. @@ -48,11 +49,11 @@ When `enable_cyclocomp` is true, the workflow uploads a `cyclocomp-results` CSV ### Adding Status Badges to `README.md` -Here's a full set of badges for the top of your package's `README.md`. Replace `` with your GitHub organization or username and `` with your package name. Note, the "Bioconductor Release" and "Bioconductor Devel" badges are not related to this workflow. Only use the codecov and pkgdown badges if you have enabled those features. If copying from raw markdown, do not include the code block starts and finishes (` ``` `) in your `README.md` file. +Here's a full set of badges for the top of your package's `README.md`. Replace `` with your GitHub organization or username and `` with your package name. Note, the "Bioconductor Release" and "Bioconductor Devel" badges are not related to this workflow. Only use the codecov and pkgdown badges if you have enabled those features. **GitHub Actions:** -``` +```markdown [![R CMD check](https://github.com///actions/workflows/ci.yml/badge.svg)](https://github.com///actions/workflows/ci.yml) [![codecov](https://codecov.io/gh///graph/badge.svg)](https://codecov.io/gh//) [![pkgdown](https://img.shields.io/badge/pkgdown-site-blue.svg)](https://.github.io//) @@ -97,22 +98,6 @@ Here's a full set of badges for the top of your package's `README.md`. Replace ` | `bioc_version` | `string` | `""` | Optional override for container tag (e.g. `devel`, `RELEASE_3_20`). | | `secrets.CODECOV_TOKEN` | secret | `""` | Optional Codecov token for coverage uploads. | -## Versioning Strategy - -When calling reusable GitHub Actions workflows, the portion after `@` can be any git reference (a tag, branch, or SHA): - -- **`@main` (Default)**: Points to the default branch (`main`). Recommended during initial development prior to formal major releases. -- **`@v1`**: Pointing callers to `@v1` relies on a floating major version tag or branch (e.g. `v1`) once major releases begin. Maintainers update `v1` whenever backwards-compatible fixes or updates are published, protecting consuming repos from unexpected breaking changes in future major revisions (`v2`). -- **`@v1.0.0`**: Pins to an exact release tag for strict reproducibility. - -For now, we are going to stick with `@main` to allow rapid propagation of changes to this workflow to all users, and use branches / PRs to test new features. - -### How to Maintain Version Tags / Branches +## Which Version to Use -1. Keep `main` as the default development branch. -2. When releasing a major version, create a tag or branch named `v1` pointing to `main`: - ```bash - # Create or move the floating v1 tag - git tag -fa v1 -m "Release v1" - git push origin v1 --force - ``` +Use `@main` for now, as in the `ci.yml` template. A floating `@v1` tag will be introduced with the first stable release. See [Versioning Strategy](technical_notes.md#versioning-strategy). diff --git a/docs/adr/0001-dynamic-container-tagging.md b/docs/adr/0001-dynamic-container-tagging.md index 6e4338a..92433f9 100644 --- a/docs/adr/0001-dynamic-container-tagging.md +++ b/docs/adr/0001-dynamic-container-tagging.md @@ -23,7 +23,7 @@ Specifically: - **Hardcoding `devel`**: This is what previous iterations of the workflow did. It was rejected because it forces developers to test release bugfixes against unstable `devel` dependencies, complicating the backporting process. - **Requiring manual input**: We could have forced maintainers to explicitly define the container tag in their `.github/workflows/check-bioc.yml` file. This was rejected because it adds boilerplate and increases the chance of human error (e.g., forgetting to update the tag when branching for a new release). -- **Matrix testing across multiple versions**: Testing against both `devel` and the current release simultaneously. This was rejected for the "Rapid Feedback Check" workflow to keep CI times fast. Maintainers wanting multi-environment testing are directed to the comprehensive R-Universe workflow instead. +- **Matrix testing across multiple versions**: Testing against both `devel` and the current release simultaneously. This was rejected for the Rapid BiocCheck Workflow to keep CI times fast. Maintainers wanting multi-environment testing are directed to the comprehensive R-Universe workflow instead. ## Consequences diff --git a/docs/index.html b/docs/index.html index 4a1095e..c505f47 100644 --- a/docs/index.html +++ b/docs/index.html @@ -294,7 +294,7 @@

Configuration

Enable pkgdown Site - Builds and deploys a pkgdown site to GitHub Pages on release branch pushes. Requires one-time repository setup. + Builds and deploys a pkgdown site to GitHub Pages on release branch pushes. Requires one-time repository setup.
@@ -304,7 +304,7 @@

Configuration

Enable Codecov - Uploads test coverage to Codecov using covr. Requires a CODECOV_TOKEN repository secret. + Uploads test coverage to Codecov using covr. Requires a CODECOV_TOKEN repository secret.
@@ -410,11 +410,7 @@

Generated YAML

// Add secrets block if codecov is enabled if (hasCodecov) { - // js-yaml handles standard objects well, but for dynamic GHA expressions like ${{ ... }} - // we can just pass it as a string and js-yaml will quote it if needed, or we can use custom type. - // Actually, js-yaml might quote strings with ${{ }}. To avoid quotes, we can post-process or let it quote. - // GHA actually supports quoted strings for expressions, e.g. CODECOV_TOKEN: "${{ secrets.CODECOV_TOKEN }}" - // But standard unquoted is cleaner. Let's let js-yaml dump it, and we will clean up quotes on expressions if present. + // js-yaml quotes the ${{ }} expression; the cleanup below removes the quotes. workflowObj.jobs.bioccheck.secrets = { CODECOV_TOKEN: '${{ secrets.CODECOV_TOKEN }}' }; diff --git a/technical_notes.md b/technical_notes.md index 1f7da50..3bd7be1 100644 --- a/technical_notes.md +++ b/technical_notes.md @@ -23,18 +23,25 @@ It uses `error_on: 'never'` so that expected BiocCheck notes from the internal s This repo contains a [DESCRIPTION](DESCRIPTION) file and [basic vignette](vignettes/canary.Rmd) to make it a valid R package that can be checked without error (with enough disabling flags invoked). -## Release & Version Tagging Checklist +## Versioning Strategy -When cutting a formal major release (e.g. `v1`, `v2`) or transitioning default references, maintainers must update the following four locations in lockstep: +The portion after `@` in a `uses:` line can be any git reference (a tag, branch, or SHA): -1. **`ci.yml`**: Update the template workflow call tag (`bioconductor/workflows/.github/workflows/bioccheck.yml@v1`). -2. **`docs/index.html`**: Update the `workflowObj.jobs.bioccheck.uses` template string (`uses: 'bioconductor/workflows/.github/workflows/bioccheck.yml@v1'`). -3. **`README.md`**: Update the Overview table workflow reference. -4. **`bioccheck_usage.md`**: Update the Versioning Strategy section notes and recommendations. +- **`@main`**: Points to the default branch. This is what `ci.yml` and the Workflow Generator currently emit, so that changes propagate to all users immediately. New features are tested on branches and PRs before merging. +- **`@v1`**: A floating major version tag, to be introduced with the first stable release. Maintainers move `v1` whenever backwards-compatible fixes are published, protecting callers from breaking changes in `v2`. +- **`@v1.0.0`**: Pins to an exact release tag for strict reproducibility. + +### Release Checklist + +When cutting a major release (e.g. `v1`) or changing the default reference, update these three locations in lockstep: + +1. **`ci.yml`**: the `uses:` line. +2. **`docs/index.html`**: the `workflowObj.jobs.bioccheck.uses` template string. +3. **`technical_notes.md`**: this section. + +Then create or move the floating tag: -### Git Tag Creation Commands ```bash -# Create or update the floating major version tag (e.g., v1) git tag -fa v1 -m "Release v1" git push origin v1 --force ``` diff --git a/workflow_comparison.md b/workflow_comparison.md deleted file mode 100644 index 0a2eaca..0000000 --- a/workflow_comparison.md +++ /dev/null @@ -1,322 +0,0 @@ -# Comparison & Diff: `bioccheck.yml` vs `waldronlab/bioc-pr-cmdcheck-pkgdown.yml` - -This document outlines the design decisions and technical differences between the new **`bioconductor/workflows/.github/workflows/bioccheck.yml`** workflow and the upstream **`waldronlab/.github/.github/workflows/bioc-pr-cmdcheck-pkgdown.yml`** workflow. - ---- - -## 1. Summary of Key Differences - -| Feature / Aspect | `waldronlab` Source Workflow | `bioconductor` (`bioccheck.yml`) | Key Advantage / Reason | -| :--- | :--- | :--- | :--- | -| **Container Tag (`DOCKER_TAG`)** | Hardcoded to `"devel"` unconditionally | **Dynamic tag resolution**: maps `RELEASE_X_Y` branch targets to `bioconductor_docker:RELEASE_X_Y` | Ensures PRs/pushes targeting Bioconductor release branches test against the matching release container rather than `devel`. | -| **Branch Override** | None | Optional `bioc_version` input parameter | Allows callers to manually override the container tag (e.g. `bioc_version: "RELEASE_3_20"`). | -| **`rcmdcheck` Severity (`error_on`)** | Hardcoded to `"error"` | **Configurable input `error_on`** (default: `"warning"`) | Allows workflows to strictly fail on warnings by default, or be set to `"error"` or `"never"`. | -| **Package Installation Method** | `remotes::install_deps()` + `BiocManager::install()` | `remotes::install_local(".", dependencies = TRUE)` | Explicitly builds and installs the local package under test in addition to installing its dependencies. | -| **`pkgdown` Deployment** | Always enabled by default (`enable_pkgdown: true`) | **Opt-in (`enable_pkgdown: false` default)** + GitHub Pages deployment | Core CI functionality works out-of-the-box without requiring GitHub Pages setup or elevated permissions unless enabled (ADR 0005). | -| **Docker Hub Image Push (`dock` job)** | Includes a job to build and push Docker images to Docker Hub | Omitted (removed unused `enable_docker` input) | Can add as an opt-in feature later. | - ---- - -## 2. Full Unified Diff - -Below is the complete unified diff comparing `waldronlab/bioc-pr-cmdcheck-pkgdown.yml` (left/minus) with `bioconductor/workflows/.github/workflows/bioccheck.yml` (right/plus): - -```diff ---- waldronlab/bioc-pr-cmdcheck-pkgdown.yml -+++ bioconductor/workflows/.github/workflows/bioccheck.yml -@@ -1,4 +1,4 @@ --name: Bioc PR CMD check & (optional) pkgdown + Docker -+name: Bioc Container Check - - on: - workflow_call: -@@ -19,26 +19,19 @@ - description: "If true, build + deploy pkgdown when on a RELEASE_* branch push" - required: false - type: boolean -- default: true -- enable_docker: -- description: "If true, build/push docker when Dockerfile exists and on devel push" -- required: false -- type: boolean -- default: true -- dockerfile_path: -- description: "Path to Dockerfile to build (if present)" -- required: false -- type: string -- default: "inst/docker/pkg/Dockerfile" -+ default: false -+ error_on: -+ description: 'Error policy for rcmdcheck (never, note, warning, error)' -+ required: false -+ type: string -+ default: 'warning' -+ bioc_version: -+ description: 'Override Bioconductor version/container tag (e.g. devel, RELEASE_3_20). Auto-derived if empty.' -+ required: false -+ type: string -+ default: '' - secrets: - CODECOV_TOKEN: -+ description: 'Token for uploading coverage to Codecov' - required: false -- DOCKERHUB_USERNAME: -- required: false -- DOCKERHUB_TOKEN: -- required: false -- --env: -- R_REMOTES_NO_ERRORS_FROM_WARNINGS: true -- GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} -- CRAN: ${{ inputs.cran }} -- -- CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} -- DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} -- DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - - jobs: - set-matrix: -- runs-on: ubuntu-24.04 -+ runs-on: ubuntu-latest - outputs: -- matrix: ${{ steps.set.outputs.matrix }} -- dockerfile_exists: ${{ steps.dockerfile.outputs.exists }} - is_release_branch: ${{ steps.branch.outputs.is_release_branch }} -- ref_name: ${{ steps.branch.outputs.ref_name }} -+ docker_tag: ${{ steps.matrix.outputs.docker_tag }} -+ checkout_ref: ${{ steps.matrix.outputs.checkout_ref }} - steps: -- - name: Determine ref name + release-branch status -- id: branch -+ - name: Set Matrix Variables -+ id: matrix - shell: bash - run: | -- # For PRs, use the target branch (base_ref). For pushes, use ref_name. -+ OVERRIDE_TAG="${{ inputs.bioc_version }}" -+ -+ if [ -n "$OVERRIDE_TAG" ]; then -+ DOCKER_TAG="$OVERRIDE_TAG" -+ REF_NAME="${GITHUB_REF_NAME}" -+ else -+ # For PRs, use the target base branch; for pushes, use the pushed branch. - if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then - REF_NAME="${{ github.base_ref }}" - else - REF_NAME="${GITHUB_REF_NAME}" - fi - -- echo "ref_name=${REF_NAME}" >> "$GITHUB_OUTPUT" -- -+ # Derive the container tag from the branch name. -+ if [[ "${REF_NAME}" =~ ^RELEASE_ ]]; then -+ DOCKER_TAG="${REF_NAME}" -+ elif [[ "${REF_NAME}" == "devel" || "${REF_NAME}" == "master" || "${REF_NAME}" == "main" ]]; then -+ DOCKER_TAG="devel" -+ else -+ DOCKER_TAG="devel" -+ fi -+ fi -+ - if [[ "${REF_NAME}" =~ ^RELEASE_ ]]; then -- echo "is_release_branch=true" >> "$GITHUB_OUTPUT" -+ IS_RELEASE="true" - else -- echo "is_release_branch=false" >> "$GITHUB_OUTPUT" -+ IS_RELEASE="false" - fi - -- - name: Set Matrix (docker tag + checkout ref) -- id: set -- shell: bash -- run: | -- DOCKER_TAG="devel" -- - if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then - CHECKOUT_REF="${{ github.event.pull_request.head.sha }}" - else -- CHECKOUT_REF="${GITHUB_REF_NAME}" -+ CHECKOUT_REF="${GITHUB_SHA}" - fi - -- MATRIX="{\"include\":[{\"docker_tag\":\"${DOCKER_TAG}\",\"checkout_ref\":\"${CHECKOUT_REF}\"}]}" -- echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT" -- -- - name: Check for Dockerfile -- id: dockerfile -- shell: bash -- run: | -- if [ -f "./${{ inputs.dockerfile_path }}" ]; then -- echo "exists=true" >> "$GITHUB_OUTPUT" -- else -- echo "exists=false" >> "$GITHUB_OUTPUT" -- fi -- - check: - needs: set-matrix - runs-on: ubuntu-latest -- strategy: -- fail-fast: false -- matrix: ${{ fromJson(needs.set-matrix.outputs.matrix) }} -- -- container: ghcr.io/bioconductor/bioconductor_docker:${{ matrix.docker_tag }} -- -+ container: -+ image: bioconductor/bioconductor_docker:${{ needs.set-matrix.outputs.docker_tag }} -+ env: -+ R_REMOTES_NO_ERRORS_FROM_WARNINGS: 'true' -+ GITHUB_PAT: ${{ github.token }} -+ _R_CHECK_CRAN_INCOMING_REMOTE_: 'false' -+ CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - steps: - - name: Checkout Repository - uses: actions/checkout@v4 - with: -- ref: ${{ matrix.checkout_ref }} -+ ref: ${{ needs.set-matrix.outputs.checkout_ref }} - -- - name: Query dependencies -- run: | -- options(repos = c(CRAN = Sys.getenv("CRAN"))) -- BiocManager::install(c("remotes", "rcmdcheck", "BiocCheck", "covr")) -- saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2) -+ - name: Query R and System Dependencies -+ id: get-deps - shell: Rscript {0} -+ run: | -+ options(repos = c(CRAN = "https://packagemanager.posit.co/cran/__linux__/noble/latest", BiocManager::repositories())) -+ if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes") -+ deps <- remotes::dev_package_deps(".", dependencies = TRUE) -+ saveRDS(deps, ".github/depends.Rds") -+ writeLines(sprintf("R-%s.%i", R.version$major, floor(as.numeric(R.version$minor))), ".github/R-version") - -- - name: Cache R packages -+ - name: Cache R Packages - uses: actions/cache@v4 - with: - path: /usr/local/lib/R/site-library -- key: ${{ runner.os }}-r-${{ matrix.checkout_ref }}-${{ hashFiles('.github/depends.Rds') }} -- restore-keys: | -- ${{ runner.os }}-r-${{ matrix.checkout_ref }}- -+ key: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1-${{ hashFiles('.github/depends.Rds') }} -+ restore-keys: ${{ runner.os }}-${{ hashFiles('.github/R-version') }}-1- - -- - name: Install GPG -- if: ${{ github.ref == 'refs/heads/devel' && github.event_name != 'pull_request' }} -- run: sudo apt-get update && sudo apt-get install -y gpg -- -- - name: Install Dependencies -- run: | -- options(repos = c(CRAN = Sys.getenv("CRAN"))) -- remotes::install_deps(dependencies = TRUE, repos = BiocManager::repositories()) -- BiocManager::install(ask = FALSE, update = TRUE) -+ - name: Install Package Dependencies - shell: Rscript {0} -+ run: | -+ options(repos = c(CRAN = "https://packagemanager.posit.co/cran/__linux__/noble/latest", BiocManager::repositories())) -+ remotes::install_local(".", dependencies = TRUE, Ncpus = parallel::detectCores()) -+ BiocManager::install(c("rcmdcheck", "BiocCheck", "covr", "pkgdown"), Ncpus = parallel::detectCores()) - -- - name: Check Package -- env: -- _R_CHECK_CRAN_INCOMING_REMOTE_: false -- run: rcmdcheck::rcmdcheck(args = "--no-manual", error_on = "error", check_dir = "check") -+ - name: Run R CMD check -+ env: -+ RCMDCHECK_ERROR_ON: ${{ inputs.error_on }} - shell: Rscript {0} -- -- - name: Test coverage -- if: ${{ success() && github.ref == 'refs/heads/devel' && github.event_name != 'pull_request' }} - run: | -- cov <- covr::package_coverage( -- quiet = FALSE, -- clean = FALSE, -- type = "all", -- install_path = file.path( -- normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), -- "package" -- ) -- ) -- covr::to_cobertura(cov) -- shell: Rscript {0} -+ allowed <- c("never", "note", "warning", "error") -+ error_on <- Sys.getenv("RCMDCHECK_ERROR_ON", unset = "warning") -+ if (!error_on %in% allowed) stop("Invalid error_on value: '", error_on, "'. Must be one of: ", paste(allowed, collapse = ", ")) -+ res <- rcmdcheck::rcmdcheck(".", args = c("--no-manual", "--as-cran"), error_on = error_on, check_dir = "check") -+ print(res) - -- - name: Upload test results to Codecov -- if: ${{ success() && github.ref == 'refs/heads/devel' && github.event_name != 'pull_request' && env.CODECOV_TOKEN != '' }} -- uses: codecov/codecov-action@v4 -- with: -- fail_ci_if_error: ${{ github.event_name != 'pull_request' && true || false }} -- file: ./cobertura.xml -- plugin: noop -- disable_search: true -- token: ${{ secrets.CODECOV_TOKEN }} -- - - name: Run BiocCheck - shell: Rscript {0} - run: | -- BiocCheck::BiocCheck( -- dir('check', 'tar.gz$', full.names = TRUE), -- `quit-with-status` = TRUE, `no-check-bioc-help` = TRUE -- ) -+ tarballs <- dir("check", pattern = "\\.tar\\.gz$", full.names = TRUE) -+ if (length(tarballs) == 0) stop("No tarball found in check/ directory") -+ BiocCheck::BiocCheck(tarballs[1], `quit-with-status` = TRUE) - - - name: Test Coverage - if: success() && needs.set-matrix.outputs.is_release_branch == 'false' && env.CODECOV_TOKEN != '' - shell: Rscript {0} - run: | - cov <- covr::package_coverage() - covr::codecov(coverage = cov, token = Sys.getenv("CODECOV_TOKEN")) - - - name: Build pkgdown Site - if: >- - ${{ - success() - && inputs.enable_pkgdown - && github.event_name != 'pull_request' - && needs.set-matrix.outputs.is_release_branch == 'true' - }} - shell: Rscript {0} - run: | - pkgdown::build_site() - -+ - name: Upload pkgdown artifact -+ if: >- -+ ${{ -+ success() -+ && inputs.enable_pkgdown -+ && github.event_name != 'pull_request' -+ && needs.set-matrix.outputs.is_release_branch == 'true' -+ }} -+ uses: actions/upload-pages-artifact@v3 -+ with: -+ path: docs - - deploy: - needs: - - check - - set-matrix - if: >- - ${{ - inputs.enable_pkgdown - && github.event_name != 'pull_request' - && needs.set-matrix.outputs.is_release_branch == 'true' - }} - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 -``` From 29e8f04799479f0de18229bebf19cff2069268b2 Mon Sep 17 00:00:00 2001 From: Levi Waldron Date: Wed, 21 Oct 2026 13:14:50 -0400 Subject: [PATCH 2/2] Rename to BiocCheck Rapid Workflow --- .github/workflows/bioccheck.yml | 2 +- README.md | 2 +- bioccheck_usage.md | 4 ++-- docs/adr/0001-dynamic-container-tagging.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/bioccheck.yml b/.github/workflows/bioccheck.yml index 166bae6..83bdf67 100644 --- a/.github/workflows/bioccheck.yml +++ b/.github/workflows/bioccheck.yml @@ -1,4 +1,4 @@ -name: Rapid BiocCheck Workflow +name: BiocCheck Rapid Workflow on: workflow_call: diff --git a/README.md b/README.md index 6c64040..515596e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Canary Check](https://github.com/bioconductor/workflows/actions/workflows/canary.yml/badge.svg)](https://github.com/bioconductor/workflows/actions/workflows/canary.yml) [![pages-build-deployment](https://github.com/bioconductor/workflows/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/bioconductor/workflows/actions/workflows/pages/pages-build-deployment) -This repository (`bioconductor/workflows`) hosts the **Rapid BiocCheck Workflow**, a reusable GitHub Actions workflow for R/Bioconductor package development. +This repository (`bioconductor/workflows`) hosts the **BiocCheck Rapid Workflow**, a reusable GitHub Actions workflow for R/Bioconductor package development. **NOTE**: This is pre-release. Please try it and file issues, but some things may not work yet. The first stable release will be tagged `v1`. diff --git a/bioccheck_usage.md b/bioccheck_usage.md index c1c4bbe..7b97032 100644 --- a/bioccheck_usage.md +++ b/bioccheck_usage.md @@ -1,6 +1,6 @@ -# Rapid BiocCheck Workflow (`bioccheck.yml`) +# BiocCheck Rapid Workflow (`bioccheck.yml`) -The **Rapid BiocCheck Workflow** runs `R CMD check` and `BiocCheck` inside the official `bioconductor/bioconductor_docker` Linux container. Because system libraries and R dependencies are pre-installed in the container, it runs quickly and is ideal for PRs and continuous commits. It tests *only* on Linux and *only* against one version of Bioconductor, chosen from the branch name. This is sufficient for most development and many Bioconductor package maintainers. +The **BiocCheck Rapid Workflow** runs `R CMD check` and `BiocCheck` inside the official `bioconductor/bioconductor_docker` Linux container. Because system libraries and R dependencies are pre-installed in the container, it runs quickly and is ideal for PRs and continuous commits. It tests *only* on Linux and *only* against one version of Bioconductor, chosen from the branch name. This is sufficient for most development and many Bioconductor package maintainers. ## How the Container Is Chosen diff --git a/docs/adr/0001-dynamic-container-tagging.md b/docs/adr/0001-dynamic-container-tagging.md index 92433f9..34ace05 100644 --- a/docs/adr/0001-dynamic-container-tagging.md +++ b/docs/adr/0001-dynamic-container-tagging.md @@ -23,7 +23,7 @@ Specifically: - **Hardcoding `devel`**: This is what previous iterations of the workflow did. It was rejected because it forces developers to test release bugfixes against unstable `devel` dependencies, complicating the backporting process. - **Requiring manual input**: We could have forced maintainers to explicitly define the container tag in their `.github/workflows/check-bioc.yml` file. This was rejected because it adds boilerplate and increases the chance of human error (e.g., forgetting to update the tag when branching for a new release). -- **Matrix testing across multiple versions**: Testing against both `devel` and the current release simultaneously. This was rejected for the Rapid BiocCheck Workflow to keep CI times fast. Maintainers wanting multi-environment testing are directed to the comprehensive R-Universe workflow instead. +- **Matrix testing across multiple versions**: Testing against both `devel` and the current release simultaneously. This was rejected for the BiocCheck Rapid Workflow to keep CI times fast. Maintainers wanting multi-environment testing are directed to the comprehensive R-Universe workflow instead. ## Consequences