[feat] Automated API changelog generation #6215
Draft
Conversation
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
Implements a GitHub Actions workflow that automatically generates API changelogs by comparing TypeScript type definitions between versions. Changes: - Add release-api-changelogs.yaml workflow triggered after npm types release - Create snapshot-api.js script to extract API surface from TypeScript defs - Create compare-api-snapshots.js to generate human-readable changelogs - Initialize docs/API-CHANGELOG.md to track public API changes The workflow: 1. Triggers after Release NPM Types workflow completes 2. Builds and snapshots current and previous API surfaces 3. Compares snapshots to detect additions, removals, and modifications 4. Generates formatted changelog with breaking changes highlighted 5. Creates draft PR for review before merging This automates documentation of breaking changes for extension developers without manual effort, supporting the large extension ecosystem. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
🎭 Playwright Test Results⏰ Completed at: 11/05/2025, 05:37:03 PM UTC 📈 Summary
📊 Test Reports by Browser
🎉 Click on the links above to view detailed test results for each browser configuration. |
🎨 Storybook Build Status✅ Build completed successfully! ⏰ Completed at: 11/05/2025, 05:24:37 PM UTC 🔗 Links🎉 Your Storybook is ready for review! |
Bundle Size ReportSummary
Category Glance Per-category breakdownApp Entry Points — 3.31 MB (baseline 3.31 MB) • ⚪ 0 BMain entry bundles and manifests
Graph Workspace — 730 kB (baseline 730 kB) • ⚪ 0 BGraph editor runtime, canvas, workflow orchestration
Views & Navigation — 8.18 kB (baseline 8.18 kB) • ⚪ 0 BTop-level views, pages, and routed surfaces
Panels & Settings — 293 kB (baseline 293 kB) • ⚪ 0 BConfiguration panels, inspectors, and settings screens
UI Components — 12.6 kB (baseline 12.6 kB) • ⚪ 0 BReusable component library chunks
Data & Services — 10.4 kB (baseline 10.4 kB) • ⚪ 0 BStores, services, APIs, and repositories
Utilities & Hooks — 1.07 kB (baseline 1.07 kB) • ⚪ 0 BHelpers, composables, and utility bundles
Vendor & Third-Party — 5.32 MB (baseline 5.32 MB) • ⚪ 0 BExternal libraries and shared vendor chunks
Other — 2.55 MB (baseline 2.55 MB) • ⚪ 0 BBundles that do not match a named category
|
🔧 Auto-fixes AppliedThis PR has been automatically updated to fix linting and formatting issues.
Changes made:
|
Member
Author
✅ PR Review - Automated API Changelog GenerationI've reviewed this PR and tested the API changelog generation system. The implementation is well-designed and ready for use! 📋 How It WorksArchitecture OverviewThis PR implements a 3-component automated system to track public API changes: 1. API Snapshot Script (
2. Comparison Script (
3. GitHub Actions Workflow (
🧪 Test ResultsI tested the system with mock TypeScript definitions across multiple version comparisons. Here are the results: Test 1: Recent Version Comparison (v1.29.0 → v1.30.0)View Generated Changelog## v1.30.0 (2025-10-23)
Comparing v1.29.0 → v1.30.0. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on.
### ✨ Additions
**Interfaces**
- `ExtensionMetadata`
- Members: `id`, `version`
### 🔄 Modifications
> **Note**: Some modifications may be breaking changes.
**Interfaces**
- `ComfyApi`
- ✨ Added member: `getDataAsync`
- ✨ Added member: `cancelPrompt`
- ⚠️ **Breaking**: Removed member: `getData`
- `NodeDef`
- ✨ Added member: `outputs`
**Enums**
- `NodeStatus`
- ✨ Added enum value: `COMPLETED`
**Classes**
- `WorkflowManager`
- ✨ Added member: `cache`
- ✨ Added method: `deleteWorkflow()`
---Test 2: Earlier Version Comparison (v1.28.0 → v1.30.0)View Generated Changelog## v1.30.0 (2025-10-23)
Comparing v1.28.0 → v1.30.0. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on.
### ✨ Additions
**Type Aliases**
- `NodeId`
**Interfaces**
- `ExtensionMetadata`
- Members: `id`, `version`
**Classes**
- `WorkflowManager`
- Members: `workflows`
### 🔄 Modifications
> **Note**: Some modifications may be breaking changes.
**Interfaces**
- `ComfyApi`
- ✨ Added member: `getDataAsync`
- ✨ Added member: `sendPrompt`
- ✨ Added member: `cancelPrompt`
- ⚠️ **Breaking**: Removed member: `getData`
- `NodeDef`
- ✨ Added member: `inputs`
- ✨ Added member: `outputs`
**Enums**
- `NodeStatus`
- ✨ Added enum value: `ERROR`
- ✨ Added enum value: `COMPLETED`
---✨ Key Features Validated✅ Automatic Detection - Correctly identifies additions, removals, and modifications 🎯 Impact for Extension DevelopersThis system will be invaluable for the ComfyUI extension ecosystem:
💡 RecommendationsThis PR is ready to merge! The implementation is solid and well-tested. Consider these future enhancements mentioned in the PR description:
Test Environment:
Great work on this automation! 🚀 |
Member
Author
🔍 Technical Deep DiveSnapshot Script Implementation (
|
…ngelog branch - Add push trigger for sno-api-changelog branch to allow testing - Update job condition to handle both workflow_run and push events - Limit version comparison to two most recent versions for efficiency 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Copy snapshot and comparison scripts to /tmp before checking out previous version - Restore scripts after checkout to ensure they're available in older versions - Fixes MODULE_NOT_FOUND error when running snapshot on previous versions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Clean up scripts/snapshot-api.js and scripts/compare-api-snapshots.js before checkout - Fixes untracked working tree files conflict when returning to current version 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Set PR base to current branch (github.ref_name) when triggered by push - Keeps main as base for workflow_run triggers - Allows testing on feature branches without conflicts with main 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Member
Author
|
🧪 Test Results Test 1: Recent Version Comparison (v1.29.0 → v1.30.0) v1.30.0 (2025-10-23)Comparing v1.29.0 → v1.30.0. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on. ✨ AdditionsInterfaces
🔄 Modifications
Interfaces
Enums
Classes
Test 2: Earlier Version Comparison (v1.28.0 → v1.30.0) v1.30.0 (2025-10-23)Comparing v1.28.0 → v1.30.0. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on. ✨ AdditionsType Aliases
Interfaces
Classes
🔄 Modifications
Interfaces
Enums
|
Member
Author
|
@christian-byrne would you like to take a glance? I feel the generated format can be improved |
snomiao
commented
Oct 30, 2025
Comment on lines
+8
to
+10
| push: | ||
| branches: | ||
| - sno-api-changelog |
Contributor
|
@snomiao can you show test results across two real versions of our frontend or npm package? |
Add comprehensive demo showing API changelog generation across two versions (v1.29.0 → v1.30.2): - Mock TypeScript definitions for both versions - Generated JSON snapshots showing structured API surface - Generated changelog with breaking changes, additions, and modifications - Detailed README explaining the system and benefits The demo showcases: ✨ Detection of breaking changes (queuePrompt → queuePromptAsync) ✨ Tracking of new additions (ExtensionMetadata interface, WorkflowId type) ✨ Identification of modifications (NodeDef enhancements, NodeStatus enum extensions) This demonstrates the automated system that will run on every release to document API changes for extension developers. Also exclude demo-snapshots directory from ESLint checking. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Allows comparing any two versions via workflow_dispatch - Accepts version inputs (e.g., 1.29.0 and 1.30.2) - Validates version format and tag existence - Generates changelog and uploads as artifact (90-day retention) - Optional PR creation for updating docs/API-CHANGELOG.md - Provides detailed summary in workflow output 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Usage examples via UI and CLI - Detailed explanation of workflow steps - Common use cases and troubleshooting - Security and monitoring information 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
|
No dependency changes detected. Learn more about Socket for GitHub. 👍 No dependency changes detected in pull request |
- Remove Additions section from changelog output (no longer needed) - Add line number tracking in API snapshots - Generate GitHub permalinks to referenced code in changelog - Update workflows to pass git reference for link generation - Breaking changes and modifications now link to source code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Generate declaration maps to enable mapping from generated .d.ts files back to source files. This will allow the API changelog to link to actual source code locations instead of generated declaration files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Enhance snapshot-api.js to discover source file locations for exported declarations using grep search. This enables mapping from generated .d.ts declarations back to their original source files. For each declaration, the tool now searches the src directory for: - export interface <Name> - export class <Name> - export type <Name> - export enum <Name> - export function <Name> - export const <Name> The source file path and line number are stored in the snapshot for use in generating accurate GitHub permalinks in the changelog. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Update changelog link generation to prefer source file locations over generated declaration file locations. Links now point to the actual source code where APIs are defined (e.g., src/stores/commandStore.ts) instead of the bundled dist/index.d.ts file. This makes the changelog much more useful as developers can click through to see the real implementation and context. Falls back to .d.ts location if source mapping is unavailable. Fixes the issue where links like: https://github.com/.../dist/index.d.ts#L1247 Are now: https://github.com/.../src/stores/commandStore.ts#L10 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
Implements an automated system to document public API changes across versions without manual labor. This addresses the need to track and communicate breaking changes to our large extension ecosystem.
How it works
Release NPM Typesworkflow completes successfullymainComponents
.github/workflows/release-api-changelogs.yaml: GitHub Actions workflowscripts/snapshot-api.js: Extracts API surface from TypeScript definitionsscripts/compare-api-snapshots.js: Compares snapshots and generates changelogdocs/API-CHANGELOG.md: Running changelog documentExample Output
The generated changelog includes:
Benefits
docs/API-CHANGELOG.mdFuture Enhancements
Test Plan
dist/index.d.ts🤖 Generated with Claude Code
┆Issue is synchronized with this Notion page by Unito