From d5f6c9dad1fc39ebb048a17b0bb8c4be2f5f9d18 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:07:57 -0700
Subject: [PATCH 01/20] feat: remove experimental from forked repo tests

---
 .github/workflows/custard-ci-dev.yaml  | 2 +-
 .github/workflows/custard-ci.yaml      | 2 +-
 .github/workflows/custard-run-dev.yaml | 2 +-
 .github/workflows/custard-run.yaml     | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/custard-ci-dev.yaml b/.github/workflows/custard-ci-dev.yaml
index e2550d0c51..24d3ce69cd 100644
--- a/.github/workflows/custard-ci-dev.yaml
+++ b/.github/workflows/custard-ci-dev.yaml
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Custard CI (dev)
+name: (legacy dev) Custard CI
 on:
   push:
     branches:
diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index de7ca11875..8adadf2369 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Custard CI
+name: (legacy) Custard CI
 on:
   push:
     branches:
diff --git a/.github/workflows/custard-run-dev.yaml b/.github/workflows/custard-run-dev.yaml
index 2f4a8dce47..5395a1e222 100644
--- a/.github/workflows/custard-run-dev.yaml
+++ b/.github/workflows/custard-run-dev.yaml
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: (experimental / dev) Custard run
+name: (dev) Custard run
 
 on:
   # Run tests when a pull request is created or updated.
diff --git a/.github/workflows/custard-run.yaml b/.github/workflows/custard-run.yaml
index 91b28a0c94..68224c8b14 100644
--- a/.github/workflows/custard-run.yaml
+++ b/.github/workflows/custard-run.yaml
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: (experimental) Custard run
+name: Custard run
 
 on:
   # Run tests when a pull request is created or updated.

From ec9f17b608904e81068c6c036fc576629de7a991 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:08:51 -0700
Subject: [PATCH 02/20] mark packages to run tests

---
 run/helloworld/index.js | 2 ++
 tpu/createVM.js         | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/run/helloworld/index.js b/run/helloworld/index.js
index 5f3289de8a..e00f8be3d5 100644
--- a/run/helloworld/index.js
+++ b/run/helloworld/index.js
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO: remove this comment, used to trigger tests for validation
+
 // [START cloudrun_helloworld_service]
 import express from 'express';
 const app = express();
diff --git a/tpu/createVM.js b/tpu/createVM.js
index 5da266fd5f..c104d58ead 100644
--- a/tpu/createVM.js
+++ b/tpu/createVM.js
@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+// TODO: remove this comment, used to trigger tests for validation
+
 'use strict';
 
 async function main(tpuClient) {

From 8f6c2ddbeeaf20389615c3ea0491f2a9c7e225bb Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:13:53 -0700
Subject: [PATCH 03/20] mark old tests as legacy

---
 .github/workflows/custard-ci.yaml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 8adadf2369..3661235f30 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: (legacy) Custard CI
+# This workflow triggers custard-run.yaml
+# TODO: remove all jobs and only keep `region-tags` job.
+name: Custard CI
 on:
   push:
     branches:
@@ -28,7 +30,7 @@ env:
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
   affected:
-    name: Finding affected tests
+    name: (legacy) Finding affected tests
     runs-on: ubuntu-latest
     timeout-minutes: 2
     outputs:
@@ -62,6 +64,7 @@ jobs:
           echo "setups=$(./cloud-samples-tools/bin/custard setup-files .github/config/nodejs.jsonc paths.txt)" >> $GITHUB_OUTPUT
 
   lint:
+    name: (legacy) lint
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -119,6 +122,7 @@ jobs:
       - run: ./.github/workflows/utils/region-tags-tests.sh
 
   test:
+    name: (legacy) test
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 120 # 2 hours hard limit

From a89cd1f5dd774fa6a4fc2d36bb39ae9c10b8a066 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:15:20 -0700
Subject: [PATCH 04/20] add more comments

---
 .github/workflows/custard-ci.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 3661235f30..f38d4357c0 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This workflow triggers custard-run.yaml
-# TODO: remove all jobs and only keep `region-tags` job.
+# IMPORTANT: DO NOT REMOVE THIS FILE!
+# This workflow triggers both custard-run.yaml and custard-run-dev.yaml.
+# TODO: to sunset old tests, remove all jobs here and only keep `region-tags` job.
 name: Custard CI
 on:
   push:

From 79cadd79887a2428ea80cee83d315418e874f8e1 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:18:25 -0700
Subject: [PATCH 05/20] add instructions to sunset old tests

---
 .github/workflows/custard-ci.yaml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index f38d4357c0..5d06c1ce65 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -14,8 +14,10 @@
 
 # IMPORTANT: DO NOT REMOVE THIS FILE!
 # This workflow triggers both custard-run.yaml and custard-run-dev.yaml.
-# TODO: to sunset old tests, remove all jobs here and only keep `region-tags` job.
-name: Custard CI
+# TODO: To sunset old tests
+#   1) Remove (legacy) from the workflow name.
+#   2) Remove `affected`, `lint`, and `test` jobs (only keep `region-tags`).
+name: (legacy) Custard CI
 on:
   push:
     branches:
@@ -31,7 +33,7 @@ env:
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
   affected:
-    name: (legacy) Finding affected tests
+    name: Finding affected tests
     runs-on: ubuntu-latest
     timeout-minutes: 2
     outputs:
@@ -65,7 +67,6 @@ jobs:
           echo "setups=$(./cloud-samples-tools/bin/custard setup-files .github/config/nodejs.jsonc paths.txt)" >> $GITHUB_OUTPUT
 
   lint:
-    name: (legacy) lint
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -123,7 +124,6 @@ jobs:
       - run: ./.github/workflows/utils/region-tags-tests.sh
 
   test:
-    name: (legacy) test
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 120 # 2 hours hard limit

From f1d89803307e4e44a31cc0a78d764954b12f6f45 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:21:09 -0700
Subject: [PATCH 06/20] rename workflow back

---
 .github/workflows/custard-ci.yaml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 5d06c1ce65..04b50503ee 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -12,12 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# IMPORTANT: DO NOT REMOVE THIS FILE!
-# This workflow triggers both custard-run.yaml and custard-run-dev.yaml.
-# TODO: To sunset old tests
-#   1) Remove (legacy) from the workflow name.
-#   2) Remove `affected`, `lint`, and `test` jobs (only keep `region-tags`).
-name: (legacy) Custard CI
+# IMPORTANT: DO NOT CHANGE THE NAME OF THIS WORKFLOW!
+# The workflow named "Custard CI" triggers both custard-run.yaml and custard-run-dev.yaml.
+# TODO: To sunset old tests remove `affected`, `lint`, and `test` jobs (only keep `region-tags`).
+name: Custard CI
 on:
   push:
     branches:
@@ -33,7 +31,7 @@ env:
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
   affected:
-    name: Finding affected tests
+    name: Finding affected tests (legacy)
     runs-on: ubuntu-latest
     timeout-minutes: 2
     outputs:
@@ -67,6 +65,7 @@ jobs:
           echo "setups=$(./cloud-samples-tools/bin/custard setup-files .github/config/nodejs.jsonc paths.txt)" >> $GITHUB_OUTPUT
 
   lint:
+    name: lint (legacy)
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -124,6 +123,7 @@ jobs:
       - run: ./.github/workflows/utils/region-tags-tests.sh
 
   test:
+    name: test (legacy)
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 120 # 2 hours hard limit

From 8d7235dbeb4908aa8998aef2295670f669790e2e Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 13:23:36 -0700
Subject: [PATCH 07/20] remove experimental from created checks

---
 .github/workflows/custard-run.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/custard-run.yaml b/.github/workflows/custard-run.yaml
index 68224c8b14..ae6f72759e 100644
--- a/.github/workflows/custard-run.yaml
+++ b/.github/workflows/custard-run.yaml
@@ -57,7 +57,7 @@ jobs:
       head-sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
       config-file: .github/config/nodejs.jsonc
       paths: ${{ (inputs.run-all && '.') || inputs.paths || '' }}
-      check-name: (experimental) Custard CI
+      check-name: Custard CI
       create-check-if: ${{ !!github.event.workflow_run }}
 
   lint:
@@ -73,7 +73,7 @@ jobs:
         with:
           sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
           status: in_progress
-          name: (experimental) Custard CI / ${{ github.job }}
+          name: Custard CI / ${{ github.job }}
           if: ${{ !!github.event.workflow_run }}
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
@@ -121,7 +121,7 @@ jobs:
         id: queued
         with:
           sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
-          name: (experimental) Custard CI / ${{ github.job }} (${{ matrix.path }})
+          name: Custard CI / ${{ github.job }} (${{ matrix.path }})
           job-name: ${{ github.job }} (${{ matrix.path }})
           if: ${{ !!github.event.workflow_run }}
       - name: Checkout

From bc1c2ba55929754add7abe8da62b6a7a9bbd721f Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 14:32:47 -0700
Subject: [PATCH 08/20] remove packages to trigger tests

---
 run/helloworld/index.js | 2 --
 tpu/createVM.js         | 2 --
 2 files changed, 4 deletions(-)

diff --git a/run/helloworld/index.js b/run/helloworld/index.js
index e00f8be3d5..5f3289de8a 100644
--- a/run/helloworld/index.js
+++ b/run/helloworld/index.js
@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// TODO: remove this comment, used to trigger tests for validation
-
 // [START cloudrun_helloworld_service]
 import express from 'express';
 const app = express();
diff --git a/tpu/createVM.js b/tpu/createVM.js
index c104d58ead..5da266fd5f 100644
--- a/tpu/createVM.js
+++ b/tpu/createVM.js
@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-// TODO: remove this comment, used to trigger tests for validation
-
 'use strict';
 
 async function main(tpuClient) {

From ef7e9ee96ce5743f9ebf1e0244df0a452ab529be Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 14:35:45 -0700
Subject: [PATCH 09/20] experiment to see if check fulfills required tests

---
 .github/workflows/custard-ci.yaml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 04b50503ee..6e7f04e1a9 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -30,6 +30,17 @@ env:
 
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
+  # TODO: REMOVE THIS BEFORE MERGING
+  experiment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create check
+        uses: GoogleCloudPlatform/cloud-samples-tools/actions/steps/create-check@9ee708234e240605d96e78f652c333ed6aa95a23 # v0.3.2
+        with:
+          sha: ${{ github.event.pull_request.head.sha }}
+          name: lint
+          status: success
+
   affected:
     name: Finding affected tests (legacy)
     runs-on: ubuntu-latest

From 86e31519ee9c94d40e9bf041cf4304f44f4ffe06 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 14:37:17 -0700
Subject: [PATCH 10/20] add permissions to experiment

---
 .github/workflows/custard-ci.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 6e7f04e1a9..47ef9cd21f 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -33,6 +33,8 @@ jobs:
   # TODO: REMOVE THIS BEFORE MERGING
   experiment:
     runs-on: ubuntu-latest
+    permissions:
+      statuses: write
     steps:
       - name: Create check
         uses: GoogleCloudPlatform/cloud-samples-tools/actions/steps/create-check@9ee708234e240605d96e78f652c333ed6aa95a23 # v0.3.2

From 4e0815c4db6e749c5d3c281b1e642fa89e845590 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 14:42:44 -0700
Subject: [PATCH 11/20] rename lint back

---
 .github/workflows/custard-ci.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 47ef9cd21f..0b3675f0fe 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -78,7 +78,6 @@ jobs:
           echo "setups=$(./cloud-samples-tools/bin/custard setup-files .github/config/nodejs.jsonc paths.txt)" >> $GITHUB_OUTPUT
 
   lint:
-    name: lint (legacy)
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 5

From 3f3afac1b8b2949a1b2a5322f94c165f5488cea8 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 14:48:09 -0700
Subject: [PATCH 12/20] remove experiment

---
 .github/workflows/custard-ci.yaml | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 0b3675f0fe..6743d15dbd 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -30,19 +30,6 @@ env:
 
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
-  # TODO: REMOVE THIS BEFORE MERGING
-  experiment:
-    runs-on: ubuntu-latest
-    permissions:
-      statuses: write
-    steps:
-      - name: Create check
-        uses: GoogleCloudPlatform/cloud-samples-tools/actions/steps/create-check@9ee708234e240605d96e78f652c333ed6aa95a23 # v0.3.2
-        with:
-          sha: ${{ github.event.pull_request.head.sha }}
-          name: lint
-          status: success
-
   affected:
     name: Finding affected tests (legacy)
     runs-on: ubuntu-latest

From 76955c3c68bb9cd4286e7940ec9247f179d4379a Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 15:30:37 -0700
Subject: [PATCH 13/20] only run tests on non-forks

---
 .github/workflows/custard-ci-dev.yaml | 1 +
 .github/workflows/custard-ci.yaml     | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.github/workflows/custard-ci-dev.yaml b/.github/workflows/custard-ci-dev.yaml
index 24d3ce69cd..a276bbb566 100644
--- a/.github/workflows/custard-ci-dev.yaml
+++ b/.github/workflows/custard-ci-dev.yaml
@@ -61,6 +61,7 @@ jobs:
           echo "setups=$(./cloud-samples-tools/bin/custard setup-files .github/config/nodejs-dev.jsonc paths.txt)" >> $GITHUB_OUTPUT
 
   nodejs-test:
+    if: github.event.pull_request && github.event.pull_request.head.repo.fork == false
     name: test
     needs: affected
     runs-on: ubuntu-latest
diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 6743d15dbd..50d254dd0b 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -122,6 +122,7 @@ jobs:
       - run: ./.github/workflows/utils/region-tags-tests.sh
 
   test:
+    if: github.event.pull_request && github.event.pull_request.head.repo.fork == false
     name: test (legacy)
     needs: affected
     runs-on: ubuntu-latest

From 4e9664beb3811dca56ed1ce9179611454cbced63 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 16:10:57 -0700
Subject: [PATCH 14/20] remove experimental

---
 .github/workflows/custard-run-dev.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/custard-run-dev.yaml b/.github/workflows/custard-run-dev.yaml
index b77b504e9c..764b521397 100644
--- a/.github/workflows/custard-run-dev.yaml
+++ b/.github/workflows/custard-run-dev.yaml
@@ -52,7 +52,7 @@ jobs:
       head-sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
       config-file: .github/config/nodejs-dev.jsonc
       paths: ${{ (inputs.run-all && '.') || inputs.paths || '' }}
-      check-name: (experimental / dev) Custard CI
+      check-name: (dev) Custard CI
       create-check-if: ${{ !!github.event.workflow_run }}
 
   test:
@@ -77,7 +77,7 @@ jobs:
         id: queued
         with:
           sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
-          name: (experimental / dev) Custard CI / ${{ github.job }} (${{ matrix.path }})
+          name: (dev) Custard CI / ${{ github.job }} (${{ matrix.path }})
           job-name: ${{ github.job }} (${{ matrix.path }})
           if: ${{ !!github.event.workflow_run }}
       - name: Checkout

From 07c8f84a08a6565d482d85204bcc24b2b614b64e Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 16:21:28 -0700
Subject: [PATCH 15/20] document ci testing

---
 .github/PULL_REQUEST_TEMPLATE.md |  1 +
 CONTRIBUTING.md                  | 57 ++++++++++++++++----------------
 2 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index cb09705a70..17591a9c5d 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -8,6 +8,7 @@ Note: Before submitting a pull request, please open an issue for discussion if y
 - [ ] I have followed guidelines from [CONTRIBUTING.MD](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md) and [Samples Style Guide](https://googlecloudplatform.github.io/samples-style-guide/)
 - [ ] **Tests** pass:   `npm test` (see [Testing](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md#run-the-tests-for-a-single-sample))
 - [ ] **Lint** pass:   `npm run lint` (see [Style](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md#style))
+- [ ] **Required CI tests** pass (see [CI testing](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md#ci-testing))
 - [ ] These samples need a new **API enabled** in testing projects to pass (let us know which ones)
 - [ ] These samples need a new/updated **env vars** in testing projects set to pass (let us know which ones)
 - [ ] This pull request is from a branch created directly off of `GoogleCloudPlatform/nodejs-docs-samples`. Not a fork.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index af25dd5ff7..1b35be6198 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -64,34 +64,35 @@ const assert = require('node:assert/strict');
 
 ### CI testing
 
-For new samples, a GitHub Actions workflow should be created to run your tests
-on the CI system:
-
-1. Check that your new samples and sample tests are on a branch created directly from this repo `GoogleCloudPlatform/nodejs-docs-samples`. Not a fork.
-
-1. Add an entry to
-   [.github/workflows/utils/workflows.json](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/.github/workflows/utils/workflows.json)
-   matching the directory with your sample code.
-
-1. From the root of the repo, generate a new workflow in the
-   [workflows](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/.github/workflows)
-   directory. You can specify a `path` to only generate the specific workflow,
-   e.g. `cloud-tasks`. If the path is omitted, all workflows will be generated.
-
-        node .github/workflows/utils/generate.js -s [path]
-
-> **Note** There are some existing samples that use an alternative CI system. It
-> is recommended to use GitHub Actions for new samples, but these instructions
-> are provided below for your reference.
->
-> Add a **build configuration file (`.cfg`)** for your samples in
-> **[`.kokoro/`](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/tree/main/.kokoro)**.
-> Check existing config files for the right format.
->
-> All tests need a corresponding job file outside of GitHub. If you are a
-> Googler, please provide the CL alongside your PR. See the internal codelab for
-> Kokoro for details. If you don't work at Google, the person reviewing your PR
-> will create the job config for you.
+> **tl;dr**: Any check with `(dev)`, `(experimental)`, or `(legacy)` can be ignored and should **not block** your PR from merging.
+
+This repository uses the 🍮 **Custard CI** from
+[`GoogleCloudPlatform/cloud-samples-tools`](https://github.com/GoogleCloudPlatform/cloud-samples-tools)
+to set up and run tests.
+
+First, it checks which files changed in a PR to find which packages were affected.
+In this repo, a _package_ is defined as a directory containing a `package.json` file.
+
+If a global file (not belonging to a package) is changed, all packages are marked as affected.
+Global files are can contain repo-level configurations that could affect other packages.
+Typically, contributors should only modify files in a package.
+
+Only affected packages are linted and tested.
+For tests, we use a
+[matrix strategy](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow)
+to generate isolated jobs for each affected test.
+
+We're working to improve the testing infrastructure, while keeping tests stable.
+This means you'll sometimes see some new experimental tests, you can generally ignore them.
+Or two versions of one test running while we make sure the new version works well.
+
+Here's a list of which tests are required and which ones you can ignore.
+* `Custard CI`: (**required**) this is the main status of the tests
+* `Custard CI / lint`: (**required**) runs only for affected packages
+* `Custard CI / test (package)`: (**required**) runs only for affected packages
+* `(dev) Custard CI / test (package)`: (_ignore_) this test has errors we're working on
+* `(experimental) Custard CI / ...`: (_ignore_) this is a new unstable version
+* `Custard CI / (legacy) ...`: (_ignore_) this is the old version running while we make sure the new one works
 
 ### TypeScript Support
 

From 25f65d7a76945f3704ec9575b5c724808944f18d Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 16:23:52 -0700
Subject: [PATCH 16/20] add legacy to old dev tests

---
 .github/workflows/custard-ci-dev.yaml | 4 ++--
 .github/workflows/custard-ci.yaml     | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/custard-ci-dev.yaml b/.github/workflows/custard-ci-dev.yaml
index a276bbb566..47d08508d9 100644
--- a/.github/workflows/custard-ci-dev.yaml
+++ b/.github/workflows/custard-ci-dev.yaml
@@ -27,7 +27,7 @@ env:
 
 jobs:
   affected:
-    name: Finding affected tests
+    name: (legacy) Finding affected tests
     runs-on: ubuntu-latest
     timeout-minutes: 2
     outputs:
@@ -62,7 +62,7 @@ jobs:
 
   nodejs-test:
     if: github.event.pull_request && github.event.pull_request.head.repo.fork == false
-    name: test
+    name: (legacy) test
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 120 # 2 hours hard limit
diff --git a/.github/workflows/custard-ci.yaml b/.github/workflows/custard-ci.yaml
index 50d254dd0b..a63e570c33 100644
--- a/.github/workflows/custard-ci.yaml
+++ b/.github/workflows/custard-ci.yaml
@@ -31,7 +31,7 @@ env:
 # TODO: remove all jobs except region-tags (should be tested by custard-run workflows)
 jobs:
   affected:
-    name: Finding affected tests (legacy)
+    name: (legacy) Finding affected tests
     runs-on: ubuntu-latest
     timeout-minutes: 2
     outputs:
@@ -123,7 +123,7 @@ jobs:
 
   test:
     if: github.event.pull_request && github.event.pull_request.head.repo.fork == false
-    name: test (legacy)
+    name: (legacy) test
     needs: affected
     runs-on: ubuntu-latest
     timeout-minutes: 120 # 2 hours hard limit

From d8cca7781971b1298c2f3f85d8eaad4f0ecb0761 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 16:34:55 -0700
Subject: [PATCH 17/20] rename summary to Custard CI / test

---
 .github/workflows/custard-run-dev.yaml | 2 +-
 .github/workflows/custard-run.yaml     | 2 +-
 CONTRIBUTING.md                        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/custard-run-dev.yaml b/.github/workflows/custard-run-dev.yaml
index 764b521397..a7f9957ae9 100644
--- a/.github/workflows/custard-run-dev.yaml
+++ b/.github/workflows/custard-run-dev.yaml
@@ -52,7 +52,7 @@ jobs:
       head-sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
       config-file: .github/config/nodejs-dev.jsonc
       paths: ${{ (inputs.run-all && '.') || inputs.paths || '' }}
-      check-name: (dev) Custard CI
+      check-name: (dev) Custard CI / tests
       create-check-if: ${{ !!github.event.workflow_run }}
 
   test:
diff --git a/.github/workflows/custard-run.yaml b/.github/workflows/custard-run.yaml
index 3110635895..c5fc5c94d2 100644
--- a/.github/workflows/custard-run.yaml
+++ b/.github/workflows/custard-run.yaml
@@ -57,7 +57,7 @@ jobs:
       head-sha: ${{ github.event.workflow_run.head_sha || inputs.ref || github.sha }}
       config-file: .github/config/nodejs.jsonc
       paths: ${{ (inputs.run-all && '.') || inputs.paths || '' }}
-      check-name: Custard CI
+      check-name: Custard CI / tests
       create-check-if: ${{ !!github.event.workflow_run }}
 
   lint:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1b35be6198..487fdc8d4a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -87,7 +87,7 @@ This means you'll sometimes see some new experimental tests, you can generally i
 Or two versions of one test running while we make sure the new version works well.
 
 Here's a list of which tests are required and which ones you can ignore.
-* `Custard CI`: (**required**) this is the main status of the tests
+* `Custard CI / tests`: (**required**) this succeeds until all tests have finished
 * `Custard CI / lint`: (**required**) runs only for affected packages
 * `Custard CI / test (package)`: (**required**) runs only for affected packages
 * `(dev) Custard CI / test (package)`: (_ignore_) this test has errors we're working on

From e3a21e550012bfcb248b12efac59196070db371d Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Mon, 12 May 2025 16:35:12 -0700
Subject: [PATCH 18/20] reorder list

---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 487fdc8d4a..2c93ca6929 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -87,8 +87,8 @@ This means you'll sometimes see some new experimental tests, you can generally i
 Or two versions of one test running while we make sure the new version works well.
 
 Here's a list of which tests are required and which ones you can ignore.
-* `Custard CI / tests`: (**required**) this succeeds until all tests have finished
 * `Custard CI / lint`: (**required**) runs only for affected packages
+* `Custard CI / tests`: (**required**) this succeeds until all tests have finished
 * `Custard CI / test (package)`: (**required**) runs only for affected packages
 * `(dev) Custard CI / test (package)`: (_ignore_) this test has errors we're working on
 * `(experimental) Custard CI / ...`: (_ignore_) this is a new unstable version

From 9855d1db28a6d251e06a18bdcf28aea6230c04a6 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Tue, 13 May 2025 14:31:05 -0700
Subject: [PATCH 19/20] Update CONTRIBUTING.md

Co-authored-by: Katie McLaughlin <katie@glasnt.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2c93ca6929..cfdb25e9da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,7 +88,7 @@ Or two versions of one test running while we make sure the new version works wel
 
 Here's a list of which tests are required and which ones you can ignore.
 * `Custard CI / lint`: (**required**) runs only for affected packages
-* `Custard CI / tests`: (**required**) this succeeds until all tests have finished
+* `Custard CI / tests`: (**required**) this runs until all tests have finished
 * `Custard CI / test (package)`: (**required**) runs only for affected packages
 * `(dev) Custard CI / test (package)`: (_ignore_) this test has errors we're working on
 * `(experimental) Custard CI / ...`: (_ignore_) this is a new unstable version

From 2f447d2fff750b8127a3a0fdcec6de9c7cabc567 Mon Sep 17 00:00:00 2001
From: David Cavazos <dcavazos@google.com>
Date: Tue, 13 May 2025 14:33:54 -0700
Subject: [PATCH 20/20] add note to pull request template

---
 .github/PULL_REQUEST_TEMPLATE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 17591a9c5d..b63c3f817f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,3 +16,5 @@ Note: Before submitting a pull request, please open an issue for discussion if y
 - [ ] This sample adds a new sample directory, and I created [GitHub Actions workflow](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md#adding-new-samples) for this sample
 - [ ] This sample adds a new **Product API**, and I updated the [Blunderbuss issue/PR auto-assigner](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/.github/blunderbuss.yml) with the codeowners for this sample
 - [ ] Please **merge** this PR for me once it is approved
+
+> **Note**: Any check with `(dev)`, `(experimental)`, or `(legacy)` can be ignored and should **not block** your PR from merging (see [CI testing](https://github.com/GoogleCloudPlatform/nodejs-docs-samples/blob/main/CONTRIBUTING.md#ci-testing)).