Simplify docs and rename to BiocCheck Rapid Workflow

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

.github/workflows/bioccheck.yml

@@ -1,4 +1,4 @@
-name: Bioc Container Check
+name: BiocCheck Rapid 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

.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'

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 **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`.
 
 ## 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 `<OWNER>` with your GitHub organization or username and `<PKGNAME>` 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.

bioccheck_usage.md

@@ -1,16 +1,17 @@
-# Rapid Feedback Container Check (`bioconductor/bioccheck` workflow)
+# BiocCheck Rapid 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 **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.
 
-## 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 `<OWNER>` with your GitHub organization or username and `<PKGNAME>` 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 `<OWNER>` with your GitHub organization or username and `<PKGNAME>` 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/<OWNER>/<PKGNAME>/actions/workflows/ci.yml/badge.svg)](https://github.com/<OWNER>/<PKGNAME>/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/<OWNER>/<PKGNAME>/graph/badge.svg)](https://codecov.io/gh/<OWNER>/<PKGNAME>)
 [![pkgdown](https://img.shields.io/badge/pkgdown-site-blue.svg)](https://<OWNER>.github.io/<PKGNAME>/)
@@ -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).

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 BiocCheck Rapid Workflow to keep CI times fast. Maintainers wanting multi-environment testing are directed to the comprehensive R-Universe workflow instead.
 
 ## Consequences
 

docs/index.html

@@ -294,7 +294,7 @@ <h2>Configuration</h2>
                     <input type="checkbox" id="opt-pkgdown">
                     <div class="label-text-wrapper">
                         <span>Enable pkgdown Site</span>
-                        <span class="help-text">Builds and deploys a pkgdown site to GitHub Pages on release branch pushes. <a href="https://github.com/bioconductor/workflows/blob/main/bioccheck_usage.md#repository-setup-for-optional-features" target="_blank" style="color: var(--accent-primary); text-decoration: none;">Requires one-time repository setup.</a></span>
+                        <span class="help-text">Builds and deploys a pkgdown site to GitHub Pages on release branch pushes. <a href="https://github.com/bioconductor/workflows/blob/main/bioccheck_usage.md#repository-configuration-for-optional-features" target="_blank" style="color: var(--accent-primary); text-decoration: none;">Requires one-time repository setup.</a></span>
                     </div>
                 </label>
             </div>
@@ -304,7 +304,7 @@ <h2>Configuration</h2>
                     <input type="checkbox" id="opt-codecov">
                     <div class="label-text-wrapper">
                         <span>Enable Codecov</span>
-                        <span class="help-text">Uploads test coverage to Codecov using covr. <a href="https://github.com/bioconductor/workflows/blob/main/bioccheck_usage.md#repository-setup-for-optional-features" target="_blank" style="color: var(--accent-primary); text-decoration: none;">Requires a CODECOV_TOKEN repository secret.</a></span>
+                        <span class="help-text">Uploads test coverage to Codecov using covr. <a href="https://github.com/bioconductor/workflows/blob/main/bioccheck_usage.md#repository-configuration-for-optional-features" target="_blank" style="color: var(--accent-primary); text-decoration: none;">Requires a CODECOV_TOKEN repository secret.</a></span>
                     </div>
                 </label>
             </div>
@@ -410,11 +410,7 @@ <h2>Generated YAML</h2>
 
                 // 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 }}'
                     };

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
 ```