Add changeset check workflow and docs

.github/pull_request_template.md

@@ -29,8 +29,9 @@ Before merging, the reviewer should check the following items:
 - [ ] If this PR includes breaking changes, do we need to update any jobs in
       production? Is it safe to release?
 - [ ] Are there any unit tests?
-- [ ] Is there a changeset associated with this PR? Should there be? Note that
-      dev only changes don't need a changeset.
+- [ ] Does every changed adaptor have a corresponding changeset? If an adaptor
+      change does not affect a release, has a maintainer applied the
+      `no changeset required` label? Repository-only changes need neither.
 - [ ] If there is a changeset, was `pnpm run version` used to bump versions (not
       `pnpm changeset version` directly)? This ensures changelog dates are stamped correctly.
 - [ ] Have you ticked a box under AI Usage?

.github/workflows/changeset.yaml

@@ -0,0 +1,58 @@
+name: Changeset
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  changeset:
+    name: Changeset required
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check whether a changeset is required
+        id: requirements
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: node scripts/check-changesets.mjs detect --base "$BASE_SHA"
+
+      - name: Record changeset exemption
+        if: >-
+          steps.requirements.outputs.required == 'true' &&
+          contains(github.event.pull_request.labels.*.name, 'no changeset required')
+        run: |
+          echo "Changeset check skipped by the 'no changeset required' label."
+          {
+            echo "## Changeset check skipped"
+            echo
+            echo "A maintainer applied the \`no changeset required\` label."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Setup pnpm
+        if: >-
+          steps.requirements.outputs.required == 'true' &&
+          !contains(github.event.pull_request.labels.*.name, 'no changeset required')
+        uses: pnpm/action-setup@v4
+
+      - name: Install changeset checker dependencies
+        if: >-
+          steps.requirements.outputs.required == 'true' &&
+          !contains(github.event.pull_request.labels.*.name, 'no changeset required')
+        run: pnpm install --filter adaptors --frozen-lockfile
+
+      - name: Validate changeset coverage
+        if: >-
+          steps.requirements.outputs.required == 'true' &&
+          !contains(github.event.pull_request.labels.*.name, 'no changeset required')
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: node scripts/check-changesets.mjs validate --base "$BASE_SHA"

README.md

@@ -222,8 +222,14 @@ in the wiki.
 
 ## Changesets
 
-Any submitted PRs should have an accompanying
-[changeset](https://github.com/changesets/changesets).
+Every submitted PR that changes one or more adaptors under `packages/` must have
+an accompanying [changeset](https://github.com/changesets/changesets) for each
+changed adaptor. A single changeset may target multiple adaptors. Repository
+tooling and top-level documentation changes do not require a changeset.
+
+The **Changeset required** GitHub check enforces this policy. It detects changed
+adaptors and verifies that every corresponding package appears in an added or
+modified changeset.
 
 - Create a new changeset with `pnpm changeset`. This will prompt you for the
   changes:
@@ -233,9 +239,14 @@ pnpm changeset
 ```
 
 > Follow the prompts to describe your changes. This will create a new changeset
-> file in the `.changesets` folder.
+> file in the `.changeset` folder.
 
 - Commit the changeset to the repo when you're ready.
+- Run `pnpm changeset:check` to verify changeset coverage before pushing.
+- Test, documentation, and development-only changes inside an adaptor directory
+  still count as adaptor changes. If such a change does not need a release, ask
+  a maintainer to apply the exact `no changeset required` label. Adding or
+  removing the label reruns the check.
 
 ## Versioning
 

package.json

@@ -10,6 +10,7 @@
     "build:tools": "pnpm --filter \"./tools/**\" build",
     "build": "pnpm build:tools && pnpm build:adaptors",
     "changelog": "pnpm -C tools/changelog update-latest-versions",
+    "changeset:check": "node scripts/check-changesets.mjs validate",
     "docs:build": "pnpm exec scripts/build-docs.sh",
     "docs:publish": "pnpm exec scripts/publish-docs.sh",
     "docs:watch": "chokidar packages/*/docs/*.md -c 'pnpm docs:build'",
@@ -21,7 +22,8 @@
     "setup": "pnpm --filter \"./tools/**\" install",
     "slack:notify": "cd tools/slack && pnpm notify",
     "test:imports": "cd tools/import-tests && pnpm test",
-    "test": "pnpm lint && pnpm --filter \"./packages/**\" test && pnpm test:imports",
+    "test": "pnpm lint && pnpm --filter \"./packages/**\" test && pnpm test:imports && pnpm test:changesets",
+    "test:changesets": "node --test scripts/check-changesets.test.mjs",
     "test:git": "pnpm exec scripts/status-check.sh",
     "validate:schemas": "node scripts/validate-configuration-schemas.mjs",
     "version": "pnpm changeset version && pnpm run changelog"
@@ -30,6 +32,7 @@
   "license": "ISC",
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@changesets/parse": "^0.4.2",
     "@openfn/adaptor-apis": "workspace:*",
     "@openfn/buildtools": "workspace:^1.0.2",
     "@openfn/generate-fhir": "workspace:^",