scripts(changelog): single-source changelog nav rendering#74
Merged
Conversation
…ring Adds `scripts/sync-changelog.py`, which regenerates the four sites the changelog lives on from a single source of truth: the frontmatter of each `changelog/*.mdx` entry. Removes the manual-maintenance burden that came up in PR #36/#37/#39 review (each changelog PR previously had to update docs.json + master index + product-page index in addition to the entry file). The script targets: - docs.json — Changelog tab year-group `pages` arrays (surgical replace) - changelog/index.mdx — master index with tag-filter UI - merge-queue/changelog.mdx — entries where category = "Merge Queue" - flaky-tests/changelog.mdx — entries where category = "Flaky Tests" Other categories (Code Quality, CI Autopilot, Web App) appear in the master index but have no product-page index per current convention. Usage: python3 scripts/sync-changelog.py apply python3 scripts/sync-changelog.py --check CI mode; exits 1 on drift Also commits a normalization pass on the 4 target files: same-day entries are now sorted alphabetically by slug (was somewhat random), and one stray blank line after frontmatter is dropped. No content changes — all 154 entries preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- changelog-check.yml: runs `sync-changelog.py --check` on PRs touching changelog files. Fails if the nav files are out of sync with entries. - changelog-sync.yml: runs on push to main. If a changelog entry landed without the nav files being regenerated, the action auto-commits the fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deliberately skipping `sync-changelog.py` so the changelog-check workflow should fail, proving it catches nav drift. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Explains the sync script workflow and the two CI checks so contributors know how to add entries correctly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/sync-changelog.pyto regenerate the four sites the changelog lives on from the frontmatter of eachchangelog/*.mdxentry.docs.json,changelog/index.mdx, and the relevant product-page index.How it works
The single source of truth is the frontmatter of each
changelog/*.mdxentry:The script reads every
changelog/*.mdx, groups by year/month and product, and rewrites:docs.json— surgically replaces theChangelogtab's year-grouppagesarrays. Newest first.changelog/index.mdx— master index with the tag-filter UI. One<Update>block per entry, grouped by## YYYYand### Month YYYY.merge-queue/changelog.mdx— same shape, filtered tocategory: Merge Queue.flaky-tests/changelog.mdx— same, filtered tocategory: Flaky Tests.Other categories (Code Quality, CI Autopilot, Web App) still appear in
docs.jsonand the master index, but have no product-page index per current convention.Usage
Idempotent — running twice produces no changes. Run after adding or editing any
changelog/*.mdxentry.Workflow going forward
Adding a new changelog entry becomes a 2-step process instead of 4:
changelog/YYYY-MM-DD-<slug>.mdxwith the canonical frontmatter shape.python3 scripts/sync-changelog.py.Same flow works for edits — touch the entry's frontmatter, re-run the script.
Follow-ups (not in this PR)
--checkon every PR touchingchangelog/and fails on drift. Catches contributors who forget to run the script.daily-devrel-scanneranddeploy-watcherto run the script after drafting a changelog entry, so the routine's PR ships fully-wired.Test plan
/changelog,/merge-queue/changelog,/flaky-tests/changelogand confirm rendering is identical to current productionpython3 scripts/sync-changelog.py --checkexits 0 after merge🤖 Generated with Claude Code