Schema-diff driven release notes

.github/workflows/bump.yml

@@ -1,8 +1,13 @@
 name: Bump version
 
-# Bumps the patch version, commits, and pushes a v* tag.
-# Pushing the tag triggers release.yml, which builds, publishes to npm,
-# and cuts a GitHub Release.
+# Fetches the latest supergraph schema, diffs it against the committed copy,
+# commits the schema update, bumps the version (minor if the schema diff has
+# breaking changes, patch otherwise), and pushes a v* tag. Pushing the tag
+# triggers release.yml, which builds and publishes to npm. The GitHub Release
+# notes lead with the schema diff, followed by auto-generated PR notes.
+#
+# If the schema is unchanged and there are no commits since the last tag,
+# the run skips the release instead of publishing an empty one.
 
 on:
   workflow_dispatch:
@@ -21,18 +26,46 @@ jobs:
         with:
           node-version: 20
       - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
       - name: Configure git
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - name: Bump patch version and tag
+      - name: Fetch latest schema and diff against committed copy
+        id: diff
+        run: |
+          cp src/resources/schema.graphql /tmp/old-schema.graphql
+          pnpm run fetch:schema
+          pnpm --silent run schema:diff /tmp/old-schema.graphql src/resources/schema.graphql > /tmp/schema-changes.md
+          cat /tmp/schema-changes.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Decide whether to release
+        id: gate
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ "${{ steps.diff.outputs.changed }}" = "true" ] || [ -z "$LAST_TAG" ] || [ -n "$(git log "$LAST_TAG"..HEAD --oneline)" ]; then
+            echo "release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            echo "Schema unchanged and no commits since $LAST_TAG — skipping release." >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - name: Commit schema update
+        if: steps.gate.outputs.release == 'true' && steps.diff.outputs.changed == 'true'
+        run: |
+          git add src/resources/schema.graphql
+          git commit -m "chore: update supergraph schema"
+      - name: Bump version and tag
+        if: steps.gate.outputs.release == 'true'
         id: bump
         run: |
-          echo "tag=$(pnpm version patch -m 'chore(release): %s')" >> "$GITHUB_OUTPUT"
+          if [ "${{ steps.diff.outputs.level }}" = "breaking" ]; then BUMP=minor; else BUMP=patch; fi
+          echo "tag=$(pnpm version $BUMP -m 'chore(release): %s')" >> "$GITHUB_OUTPUT"
       - name: Push commit and tag
+        if: steps.gate.outputs.release == 'true'
         run: git push --follow-tags
       - name: Create GitHub Release
+        if: steps.gate.outputs.release == 'true'
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ steps.bump.outputs.tag }}
+          body_path: /tmp/schema-changes.md
           generate_release_notes: true

.gitignore

@@ -6,8 +6,11 @@ coverage
 dist
 yarn-error.log
 
-# Generated resources (all regenerated at build time)
-src/resources/
+# Generated resources (regenerated at build time), except the schema —
+# it's tracked so releases record schema changes and builds are reproducible.
+# fetch:schema updates it; build reads the committed copy.
+src/resources/*
+!src/resources/schema.graphql
 
 # Published copy of the schema (regenerated by fetch:schema)
 /schema.graphql

package.json

@@ -19,12 +19,14 @@
   "scripts": {
     "prebuild": "pnpm run clean && pnpm run generate:configs",
     "clean": "rm -rf dist dist-esm",
-    "build": "pnpm run fetch:schema && pnpm run generate:graphql && pnpm run build:sdk && pnpm run codegen && pnpm run lint ./src/sdk --fix && pnpm run build:types",
+    "build": "pnpm run copy:schema && pnpm run generate:graphql && pnpm run build:sdk && pnpm run codegen && pnpm run lint ./src/sdk --fix && pnpm run build:types",
     "build:types": "pnpm run build:cjs && pnpm run build:esm && pnpm run build:rename-esm",
     "build:cjs": "tsc",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:rename-esm": "find dist-esm -name '*.js' -exec sh -c 'mv \"$1\" \"${1%.js}.mjs\"' _ {} \\; && cp -r dist-esm/* dist/ && rm -rf dist-esm",
     "fetch:schema": "curl -s https://graph.codex.io/schema/latest.graphql --output src/resources/schema.graphql && cp src/resources/schema.graphql schema.graphql",
+    "copy:schema": "cp src/resources/schema.graphql schema.graphql",
+    "schema:diff": "tsx src/scripts/schemaDiff.ts",
     "generate:configs": "tsx src/scripts/generateNetworkConfigs.ts",
     "generate:graphql": "tsx src/scripts/generateGraphql.ts",
     "build:sdk": "tsx src/scripts/buildSdk.ts",
@@ -72,6 +74,7 @@
     "@graphql-codegen/introspection": "4.0.0",
     "@graphql-codegen/typescript": "4.0.1",
     "@graphql-eslint/eslint-plugin": "^3.20.1",
+    "@graphql-inspector/core": "^7.1.3",
     "@graphql-tools/wrap": "^10.0.5",
     "@types/jest": "^29.5.4",
     "@types/lodash": "^4.17.7",