⚡️ Split GraphQL changelog by year (#60819)

heiskr · Copilot · web-flow · commit dd57bc1e7e56 · 2026-04-20T19:34:18.000Z
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/content/graphql/overview/changelog/2017.md b/content/graphql/overview/changelog/2017.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2017"
+shortTitle: "2017"
+intro: 'GraphQL schema changes from 2017.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2018.md b/content/graphql/overview/changelog/2018.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2018"
+shortTitle: "2018"
+intro: 'GraphQL schema changes from 2018.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2019.md b/content/graphql/overview/changelog/2019.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2019"
+shortTitle: "2019"
+intro: 'GraphQL schema changes from 2019.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2020.md b/content/graphql/overview/changelog/2020.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2020"
+shortTitle: "2020"
+intro: 'GraphQL schema changes from 2020.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2021.md b/content/graphql/overview/changelog/2021.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2021"
+shortTitle: "2021"
+intro: 'GraphQL schema changes from 2021.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2022.md b/content/graphql/overview/changelog/2022.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2022"
+shortTitle: "2022"
+intro: 'GraphQL schema changes from 2022.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2023.md b/content/graphql/overview/changelog/2023.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2023"
+shortTitle: "2023"
+intro: 'GraphQL schema changes from 2023.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2024.md b/content/graphql/overview/changelog/2024.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2024"
+shortTitle: "2024"
+intro: 'GraphQL schema changes from 2024.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2025.md b/content/graphql/overview/changelog/2025.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2025"
+shortTitle: "2025"
+intro: 'GraphQL schema changes from 2025.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/2026.md b/content/graphql/overview/changelog/2026.md
@@ -0,0 +1,8 @@
+---
+title: "GraphQL changelog for 2026"
+shortTitle: "2026"
+intro: 'GraphQL schema changes from 2026.'
+versions:
+  fpt: '*'
+autogenerated: graphql
+---
diff --git a/content/graphql/overview/changelog/index.md b/content/graphql/overview/changelog/index.md
@@ -6,6 +6,17 @@ redirect_from:
 versions:
   fpt: '*'
 autogenerated: graphql
+children:
+  - /2026
+  - /2025
+  - /2024
+  - /2023
+  - /2022
+  - /2021
+  - /2020
+  - /2019
+  - /2018
+  - /2017
 category:
   - Understand API changes and limits
 ---
diff --git a/src/article-api/templates/graphql-changelog.template.md b/src/article-api/templates/graphql-changelog.template.md
@@ -4,6 +4,8 @@
 
 {{ manualContent }}
 
+{% for navItem in yearNavItems %}{% if navItem.isCurrent %}**{{ navItem.year }}**{% else %}[{{ navItem.year }}]({{ navItem.year }}){% endif %}{% unless forloop.last %} · {% endunless %}{% endfor %}
+
 {% for item in changelogItems %}
 
 ## Schema changes for {{ item.date }}
diff --git a/src/article-api/tests/graphql-transformer.ts b/src/article-api/tests/graphql-transformer.ts
@@ -233,7 +233,7 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
   })
 
   describe('Overview pages', () => {
-    test('changelog page renders with changes', async () => {
+    test('changelog index page renders with latest year changes', async () => {
       const res = await getCached('/en/graphql/overview/changelog')
       expect(res.statusCode).toBe(200)
 
@@ -250,16 +250,38 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
         'Breaking changes include changes that will break existing queries',
       )
 
-      // Check for date-based changelog sections
-      expect(res.body).toContain('## Schema changes for 2025-11-30')
+      // Index page shows latest year (2026) entries only
+      expect(res.body).toContain('## Schema changes for 2026-')
 
       // Check for change items
       expect(res.body).toContain('### The GraphQL schema includes these changes:')
-      expect(res.body).toContain('Type SuggestedReviewerActor was added')
+
+      // Should NOT contain entries from other years
+      expect(res.body).not.toContain('## Schema changes for 2025-')
+
+      // Check for year navigation
+      expect(res.body).toContain('2026')
+      expect(res.body).toContain('2025')
+    })
+
+    test('changelog year page renders with that year only', async () => {
+      const res = await getCached('/en/graphql/overview/changelog/2025')
+      expect(res.statusCode).toBe(200)
+
+      // Check for year-specific heading
+      expect(res.body).toContain('# GraphQL changelog for 2025')
+
+      // Check for date-based changelog sections from 2025
+      expect(res.body).toContain('## Schema changes for 2025-')
+
+      // Should NOT contain entries from other years
+      expect(res.body).not.toContain('## Schema changes for 2026-')
+      expect(res.body).not.toContain('## Schema changes for 2024-')
     })
 
     test('changelog removes HTML tags from changes', async () => {
-      const res = await getCached('/en/graphql/overview/changelog')
+      // Use a year page that has the specific test data
+      const res = await getCached('/en/graphql/overview/changelog/2025')
       expect(res.statusCode).toBe(200)
 
       // Check that HTML tags are removed
diff --git a/src/article-api/transformers/graphql-changelog-transformer.ts b/src/article-api/transformers/graphql-changelog-transformer.ts
@@ -22,9 +22,22 @@ export class GraphQLChangelogTransformer implements PageTransformer {
   async transform(page: Page, _pathname: string, context: Context): Promise<string> {
     const currentVersion = context.currentVersion!
 
-    const { getGraphqlChangelog } = await import('@/graphql/lib/index')
+    const { getGraphqlChangelogByYear, getGraphqlChangelogYears } =
+      await import('@/graphql/lib/index')
 
-    const schema = getGraphqlChangelog(currentVersion) as ChangelogItemT[]
+    // Determine if this is a year-specific page
+    const yearMatch = page.relativePath.match(/changelog\/(\d{4})\.md$/)
+    const year = yearMatch ? Number(yearMatch[1]) : null
+    const years = getGraphqlChangelogYears(currentVersion)
+
+    let schema: ChangelogItemT[]
+    if (year) {
+      schema = getGraphqlChangelogByYear(currentVersion, year) as ChangelogItemT[]
+    } else {
+      // Index page: show only the latest year
+      const latestYear = years[0]
+      schema = getGraphqlChangelogByYear(currentVersion, latestYear) as ChangelogItemT[]
+    }
 
     const intro = page.intro ? await page.renderProp('intro', context, { textOnly: true }) : ''
     const manualContent = await extractManualContent(page, context)
@@ -51,11 +64,19 @@ export class GraphQLChangelogTransformer implements PageTransformer {
       }
     })
 
+    // Build year navigation links
+    const displayYear = year || years[0]
+    const yearNavItems = years.map((y) => ({
+      year: y,
+      isCurrent: y === displayYear,
+    }))
+
     const templateData: Record<string, unknown> = {
       pageTitle: page.title,
       pageIntro: intro,
       manualContent,
       changelogItems,
+      yearNavItems,
     }
 
     const templateContent = loadTemplate(this.templateName)
diff --git a/src/fixtures/fixtures/content/graphql/overview/changelog/2024.md b/src/fixtures/fixtures/content/graphql/overview/changelog/2024.md
@@ -0,0 +1,10 @@
+---
+title: "GraphQL changelog for 2024"
+shortTitle: "2024"
+intro: 'GraphQL schema changes from 2024.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+autogenerated: graphql
+---
diff --git a/src/fixtures/fixtures/content/graphql/overview/changelog/2025.md b/src/fixtures/fixtures/content/graphql/overview/changelog/2025.md
@@ -0,0 +1,10 @@
+---
+title: "GraphQL changelog for 2025"
+shortTitle: "2025"
+intro: 'GraphQL schema changes from 2025.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+autogenerated: graphql
+---
diff --git a/src/fixtures/fixtures/content/graphql/overview/changelog/2026.md b/src/fixtures/fixtures/content/graphql/overview/changelog/2026.md
@@ -0,0 +1,10 @@
+---
+title: "GraphQL changelog for 2026"
+shortTitle: "2026"
+intro: 'GraphQL schema changes from 2026.'
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '*'
+autogenerated: graphql
+---
diff --git a/src/fixtures/fixtures/content/graphql/overview/changelog/index.md b/src/fixtures/fixtures/content/graphql/overview/changelog/index.md
@@ -6,8 +6,12 @@ versions:
   ghec: '*'
   ghes: '*'
 autogenerated: graphql
+children:
+  - /2026
+  - /2025
+  - /2024
 ---
 
 Breaking changes include changes that will break existing queries or could affect the runtime behavior of clients. For a list of breaking changes and when they will occur, see our breaking changes log.
 
-<!-- Content after this section is automatically generated -->
+<!-- Content after this section is automatically generated -->
diff --git a/src/graphql/components/Changelog.tsx b/src/graphql/components/Changelog.tsx
@@ -8,9 +8,29 @@ import styles from '@/frame/components/ui/MarkdownContent/MarkdownContent.module
 
 type Props = {
   changelogItems: ChangelogItemT[]
+  years?: number[]
+  currentYear?: number
 }
 
-export function Changelog({ changelogItems }: Props) {
+function YearNav({ years, currentYear }: { years: number[]; currentYear: number }) {
+  return (
+    <nav aria-label="Changelog years" className="d-flex flex-wrap mb-4">
+      {years.map((year) =>
+        year === currentYear ? (
+          <span key={year} className="text-bold mr-3">
+            {year}
+          </span>
+        ) : (
+          <a key={year} className="mr-3" href={String(year)}>
+            {year}
+          </a>
+        ),
+      )}
+    </nav>
+  )
+}
+
+export function Changelog({ changelogItems, years, currentYear }: Props) {
   const slugger = new GithubSlugger()
 
   const changes = changelogItems.map((item, index) => {
@@ -45,14 +65,21 @@ export function Changelog({ changelogItems }: Props) {
         {(item.upcomingChanges || []).map((change, changeIndex) => (
           <React.Fragment key={changeIndex}>
             <p>{change.title}</p>
-            {change.changes.map((changeItem) => (
-              <li key={changeItem} dangerouslySetInnerHTML={{ __html: changeItem }} />
-            ))}
+            <ul>
+              {change.changes.map((changeItem) => (
+                <li key={changeItem} dangerouslySetInnerHTML={{ __html: changeItem }} />
+              ))}
+            </ul>
           </React.Fragment>
         ))}
       </div>
     )
   })
 
-  return <div className={cx(styles.markdownBody)}>{changes}</div>
+  return (
+    <div className={cx(styles.markdownBody)}>
+      {years && currentYear && <YearNav years={years} currentYear={currentYear} />}
+      {changes}
+    </div>
+  )
 }
diff --git a/src/graphql/lib/index.ts b/src/graphql/lib/index.ts
@@ -50,6 +50,26 @@ export function getGraphqlChangelog(version: string): any {
   return changelog.get(graphqlVersion)
 }
 
+/**
+ * Return changelog entries filtered by year.
+ */
+export function getGraphqlChangelogByYear(version: string, year: number): any[] {
+  const all = getGraphqlChangelog(version) as Array<{ date: string }>
+  return all.filter((entry) => entry.date.startsWith(String(year)))
+}
+
+/**
+ * Return the distinct years present in the changelog, sorted descending (newest first).
+ */
+export function getGraphqlChangelogYears(version: string): number[] {
+  const all = getGraphqlChangelog(version) as Array<{ date: string }>
+  const years = new Set<number>()
+  for (const entry of all) {
+    years.add(Number(entry.date.slice(0, 4)))
+  }
+  return [...years].sort((a, b) => b - a)
+}
+
 // Using any for return type as the breaking changes structure is dynamically loaded from JSON
 export function getGraphqlBreakingChanges(version: string): any {
   const graphqlVersion: string = getGraphqlVersion(version)
diff --git a/src/graphql/pages/changelog-year.tsx b/src/graphql/pages/changelog-year.tsx
diff --git a/src/graphql/pages/changelog.tsx b/src/graphql/pages/changelog.tsx
diff --git a/src/graphql/scripts/build-changelog.ts b/src/graphql/scripts/build-changelog.ts
diff --git a/src/graphql/tests/build-changelog.ts b/src/graphql/tests/build-changelog.ts
diff --git a/src/pages/[versionId]/graphql/overview/changelog/[year].tsx b/src/pages/[versionId]/graphql/overview/changelog/[year].tsx
diff --git a/src/pages/[versionId]/graphql/overview/changelog/index.tsx b/src/pages/[versionId]/graphql/overview/changelog/index.tsx
