Make GraphQL changelog script future-compatible with new change types (#56276)

Author: heiskr

.github/workflows/sync-graphql.yml

@@ -17,11 +17,16 @@ jobs:
   update_graphql_files:
     if: github.repository == 'github/docs-internal'
     runs-on: ubuntu-latest
+    outputs:
+      ignored-changes: ${{ steps.sync.outputs.ignored-changes }}
+      ignored-count: ${{ steps.sync.outputs.ignored-count }}
+      ignored-types: ${{ steps.sync.outputs.ignored-types }}
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: ./.github/actions/node-npm-setup
       - name: Run updater scripts
+        id: sync
         env:
           # need to use a token from a user with access to github/github for this step
           GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
@@ -70,3 +75,22 @@ jobs:
         with:
           slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
           slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+
+  notify_ignored_changes:
+    if: github.repository == 'github/docs-internal' && needs.update_graphql_files.outputs.ignored-count > 0 && github.event_name != 'workflow_dispatch'
+    needs: update_graphql_files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: ./.github/actions/slack-alert
+        with:
+          slack_channel_id: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }}
+          slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          color: warning
+          message: |
+            ⚠️ GraphQL Sync found ${{ needs.update_graphql_files.outputs.ignored-count }} ignored change types: ${{ needs.update_graphql_files.outputs.ignored-types }}
+
+            These change types are not in CHANGES_TO_REPORT and were silently ignored. Consider reviewing if they should be added to the changelog.
+
+            See workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

src/graphql/scripts/build-changelog.js

@@ -50,21 +50,34 @@ export async function createChangelogEntry(
   // Generate changes between the two schemas
   const changes = await diff(oldSchema, newSchema)
   const changesToReport = []
+  const ignoredChanges = []
   changes.forEach((change) => {
     if (CHANGES_TO_REPORT.includes(change.type)) {
       changesToReport.push(change)
-    } else if (CHANGES_TO_IGNORE.includes(change.type)) {
-      // Do nothing
     } else {
-      console.error('Change object causing error:')
-      console.error(change)
-      throw new Error(
-        'This change type should be added to CHANGES_TO_REPORT or CHANGES_TO_IGNORE: ' +
-          change.type,
-      )
+      // Track ignored changes for visibility
+      ignoredChanges.push(change)
     }
   })
 
+  // Log warnings for ignored change types to provide visibility
+  if (ignoredChanges.length > 0) {
+    const ignoredTypes = [...new Set(ignoredChanges.map((change) => change.type))]
+    console.warn(
+      `⚠️  GraphQL changelog: Ignoring ${ignoredChanges.length} changes of ${ignoredTypes.length} type(s):`,
+    )
+    ignoredTypes.forEach((type) => {
+      const count = ignoredChanges.filter((change) => change.type === type).length
+      console.warn(`   - ${type} (${count} change${count > 1 ? 's' : ''})`)
+    })
+    console.warn(
+      '   These change types are not in CHANGES_TO_REPORT and will not appear in the changelog.',
+    )
+  }
+
+  // Store ignored changes for potential workflow outputs
+  createChangelogEntry.lastIgnoredChanges = ignoredChanges
+
   const { schemaChangesToReport, previewChangesToReport } = segmentPreviewChanges(
     changesToReport,
     previews,
@@ -276,40 +289,36 @@ const CHANGES_TO_REPORT = [
   ChangeType.DirectiveUsageFieldDefinitionRemoved,
 ]
 
-const CHANGES_TO_IGNORE = [
-  ChangeType.FieldArgumentDescriptionChanged,
-  ChangeType.DirectiveRemoved,
-  ChangeType.DirectiveAdded,
-  ChangeType.DirectiveDescriptionChanged,
-  ChangeType.DirectiveLocationAdded,
-  ChangeType.DirectiveLocationRemoved,
-  ChangeType.DirectiveArgumentAdded,
-  ChangeType.DirectiveArgumentRemoved,
-  ChangeType.DirectiveArgumentDescriptionChanged,
-  ChangeType.DirectiveArgumentDefaultValueChanged,
-  ChangeType.DirectiveArgumentTypeChanged,
-  ChangeType.DirectiveUsageArgumentDefinitionRemoved,
-  ChangeType.EnumValueDescriptionChanged,
-  ChangeType.EnumValueDeprecationReasonChanged,
-  ChangeType.EnumValueDeprecationReasonAdded,
-  ChangeType.EnumValueDeprecationReasonRemoved,
-  ChangeType.FieldDescriptionChanged,
-  ChangeType.FieldDescriptionAdded,
-  ChangeType.FieldDescriptionRemoved,
-  ChangeType.FieldDeprecationAdded,
-  ChangeType.FieldDeprecationRemoved,
-  ChangeType.FieldDeprecationReasonChanged,
-  ChangeType.FieldDeprecationReasonAdded,
-  ChangeType.FieldDeprecationReasonRemoved,
-  ChangeType.InputFieldDescriptionAdded,
-  ChangeType.InputFieldDescriptionRemoved,
-  ChangeType.InputFieldDescriptionChanged,
-  ChangeType.TypeDescriptionChanged,
-  ChangeType.TypeDescriptionRemoved,
-  ChangeType.TypeDescriptionAdded,
-  ChangeType.DirectiveUsageFieldDefinitionAdded,
-  ChangeType.DirectiveUsageArgumentDefinitionAdded,
-  ChangeType.DirectiveUsageEnumValueAdded,
-]
+// CHANGES_TO_IGNORE list removed - now we only process changes explicitly listed
+// in CHANGES_TO_REPORT and silently ignore all others for future compatibility
+
+/**
+ * Get the ignored change types from the last changelog entry creation
+ * @returns {Array} Array of ignored change objects
+ */
+export function getLastIgnoredChanges() {
+  return createChangelogEntry.lastIgnoredChanges || []
+}
+
+/**
+ * Get summary of ignored change types for workflow outputs
+ * @returns {Object} Summary with counts and types
+ */
+export function getIgnoredChangesSummary() {
+  const ignored = getLastIgnoredChanges()
+  if (ignored.length === 0) return null
+
+  const types = [...new Set(ignored.map((change) => change.type))]
+  const summary = {
+    totalCount: ignored.length,
+    typeCount: types.length,
+    types: types.map((type) => ({
+      type,
+      count: ignored.filter((change) => change.type === type).length,
+    })),
+  }
+
+  return summary
+}
 
 export default { createChangelogEntry, cleanPreviewTitle, previewAnchor, prependDatedEntry }

src/graphql/scripts/sync.js

@@ -1,4 +1,5 @@
 import fs from 'fs/promises'
+import { appendFileSync } from 'fs'
 import path from 'path'
 import { mkdirp } from 'mkdirp'
 import yaml from 'js-yaml'
@@ -8,7 +9,11 @@ import { allVersions } from '@/versions/lib/all-versions'
 import processPreviews from './utils/process-previews'
 import processUpcomingChanges from './utils/process-upcoming-changes'
 import processSchemas from './utils/process-schemas'
-import { prependDatedEntry, createChangelogEntry } from './build-changelog'
+import {
+  prependDatedEntry,
+  createChangelogEntry,
+  getIgnoredChangesSummary,
+} from './build-changelog'
 
 const graphqlStaticDir = 'src/graphql/data'
 const dataFilenames = JSON.parse(await fs.readFile('src/graphql/scripts/utils/data-filenames.json'))
@@ -22,6 +27,8 @@ const versionsToBuild = Object.keys(allVersions)
 
 main()
 
+let allIgnoredChanges = []
+
 async function main() {
   for (const version of versionsToBuild) {
     // Get the relevant GraphQL name  for the current version
@@ -77,11 +84,42 @@ async function main() {
           path.join(graphqlStaticDir, graphqlVersion, 'changelog.json'),
         )
       }
+
+      // Capture ignored changes for potential workflow notifications
+      const ignoredSummary = getIgnoredChangesSummary()
+      if (ignoredSummary) {
+        allIgnoredChanges.push({
+          version: graphqlVersion,
+          ...ignoredSummary,
+        })
+      }
     }
   }
 
   // Ensure the YAML linter runs before checkinging in files
   execSync('npx prettier -w "**/*.{yml,yaml}"')
+
+  // Output ignored changes for GitHub Actions
+  if (allIgnoredChanges.length > 0) {
+    const totalIgnored = allIgnoredChanges.reduce((sum, item) => sum + item.totalCount, 0)
+    const uniqueTypes = [
+      ...new Set(allIgnoredChanges.flatMap((item) => item.types.map((t) => t.type))),
+    ]
+
+    console.log(
+      '::notice title=GraphQL Ignored Changes::Found ignored change types that may need review',
+    )
+
+    // Write outputs to GitHub Actions output file
+    if (process.env.GITHUB_OUTPUT) {
+      appendFileSync(
+        process.env.GITHUB_OUTPUT,
+        `ignored-changes=${JSON.stringify(allIgnoredChanges)}\n`,
+      )
+      appendFileSync(process.env.GITHUB_OUTPUT, `ignored-count=${totalIgnored}\n`)
+      appendFileSync(process.env.GITHUB_OUTPUT, `ignored-types=${uniqueTypes.join(', ')}\n`)
+    }
+  }
 }
 
 // get latest from github/github

src/graphql/tests/build-changelog.js

@@ -9,6 +9,8 @@ import {
   cleanPreviewTitle,
   previewAnchor,
   prependDatedEntry,
+  getLastIgnoredChanges,
+  getIgnoredChangesSummary,
 } from '../scripts/build-changelog'
 import readJsonFile from '@/frame/lib/read-json-file'
 
@@ -22,6 +24,60 @@ describe('creating a changelog from old schema and new schema', () => {
     MockDate.reset()
   })
 
+  test('ignores unknown change types without throwing errors', async () => {
+    // Create a minimal test that would generate an unknown change type
+    // This test ensures the system gracefully handles new change types
+    const oldSchemaString = `
+    type Query {
+      field: String
+    }
+    `
+
+    const newSchemaString = `
+    """
+    Updated description for Query type
+    """
+    type Query {
+      field: String
+    }
+    `
+
+    // This should generate TypeDescriptionAdded change type
+    // which should be silently ignored if not in CHANGES_TO_REPORT
+    const entry = await createChangelogEntry(oldSchemaString, newSchemaString, [], [], [])
+
+    // Should return null since TypeDescriptionAdded is not in CHANGES_TO_REPORT
+    // and will be silently ignored without throwing an error
+    expect(entry).toBeNull()
+  })
+
+  test('handles new directive usage change types gracefully', async () => {
+    // Test that verifies the system can handle new directive-related change types
+    // that were previously causing errors in the pipeline
+    const oldSchemaString = `
+    directive @example on FIELD_DEFINITION
+
+    type Query {
+      field: String
+    }
+    `
+
+    const newSchemaString = `
+    directive @example on FIELD_DEFINITION
+
+    type Query {
+      field: String @example
+    }
+    `
+
+    // This should generate DirectiveUsage* change types that are not in CHANGES_TO_REPORT
+    // The system should silently ignore these and not throw errors
+    const entry = await createChangelogEntry(oldSchemaString, newSchemaString, [], [], [])
+
+    // Should return null since directive usage changes are typically ignored
+    expect(entry).toBeNull()
+  })
+
   test('finds a diff of schema changes, upcoming changes, and preview changes', async () => {
     const oldSchemaString = `
     type PreviewType {
@@ -146,3 +202,71 @@ describe('updating the changelog file', () => {
     expect(JSON.parse(newContents)).toEqual(expectedUpdatedChangelogFile)
   })
 })
+
+describe('ignored changes tracking', () => {
+  test('tracks ignored change types', async () => {
+    const oldSchemaString = `
+    type Query {
+      field: String
+    }
+    `
+
+    const newSchemaString = `
+    """
+    Updated description for Query type
+    """
+    type Query {
+      field: String
+    }
+    `
+
+    // This should generate a TypeDescriptionAdded change type that gets ignored
+    await createChangelogEntry(oldSchemaString, newSchemaString, [], [], [])
+
+    const ignoredChanges = getLastIgnoredChanges()
+    expect(ignoredChanges.length).toBe(1)
+    expect(ignoredChanges[0].type).toBe('TYPE_DESCRIPTION_ADDED')
+  })
+
+  test('provides ignored changes summary', async () => {
+    const oldSchemaString = `
+    directive @example on FIELD_DEFINITION
+    type Query {
+      field1: String
+      field2: Int
+    }
+    `
+
+    const newSchemaString = `
+    directive @example on FIELD_DEFINITION
+    type Query {
+      field1: String @example
+      field2: Int @example
+    }
+    `
+
+    // This should generate multiple DirectiveUsage changes that get ignored
+    await createChangelogEntry(oldSchemaString, newSchemaString, [], [], [])
+
+    const summary = getIgnoredChangesSummary()
+    expect(summary).toBeTruthy()
+    expect(summary.totalCount).toBe(2)
+    expect(summary.typeCount).toBe(1)
+    expect(summary.types[0].type).toBe('DIRECTIVE_USAGE_FIELD_DEFINITION_ADDED')
+    expect(summary.types[0].count).toBe(2)
+  })
+
+  test('returns null summary when no changes ignored', async () => {
+    const schemaString = `
+    type Query {
+      field: String
+    }
+    `
+
+    // No changes should be generated
+    await createChangelogEntry(schemaString, schemaString, [], [], [])
+
+    const summary = getIgnoredChangesSummary()
+    expect(summary).toBeNull()
+  })
+})