ComfyUI_frontend/demo-snapshots

API Changelog Generation Demo

This demo showcases the automated API changelog generation system comparing two versions of the ComfyUI Frontend public API.

Overview

The demo compares v1.29.0 → v1.30.2 to demonstrate:

• Breaking change detection
• API additions tracking
• Non-breaking modifications
• Human-readable changelog generation

Demo Files

Input Files

• v1.29.0.d.ts - TypeScript definitions representing the v1.29.0 API surface
• v1.30.2.d.ts - TypeScript definitions representing the v1.30.2 API surface

Generated Files

• v1.29.0.json - Structured API snapshot from v1.29.0
• v1.30.2.json - Structured API snapshot from v1.30.2
• CHANGELOG-DEMO.md - Generated changelog comparing the two versions

Running the Demo

# Generate API snapshots
node scripts/snapshot-api.js demo-snapshots/v1.29.0.d.ts > demo-snapshots/v1.29.0.json
node scripts/snapshot-api.js demo-snapshots/v1.30.2.d.ts > demo-snapshots/v1.30.2.json

# Compare snapshots and generate changelog
node scripts/compare-api-snapshots.js \
  demo-snapshots/v1.29.0.json \
  demo-snapshots/v1.30.2.json \
  1.29.0 \
  1.30.2 \
  > demo-snapshots/CHANGELOG-DEMO.md

Key Changes Detected

⚠️ Breaking Changes

1. ComfyApi.queuePrompt() removed
   • Replaced with queuePromptAsync() which includes additional options
   • Extension developers need to update their code to use the new async method

✨ New Additions

1. New Interface: ExtensionMetadata

   • Provides metadata for extensions
   • Fields: id, name, version, description

2. New Type: WorkflowId

   • Type alias for workflow identifiers

3. Enhanced ComfyApi Interface

   • queuePromptAsync() - Async queue with priority support
   • cancelPrompt() - Cancel queued prompts
   • getQueueStatus() - Query queue state

4. Extended NodeDef Interface

   • input - Input specification
   • output - Output types
   • output_name - Output names

5. Enhanced NodeStatus Enum

   • Added ERROR state
   • Added COMPLETED state

6. Extended WorkflowManager Class

   • cache property for workflow caching
   • deleteWorkflow() method
   • searchWorkflows() method

🔄 Non-Breaking Modifications

1. WorkflowMetadata enhancements
   • Added optional tags field
   • Added optional thumbnail field

Real-World Usage

In production, this system will:

1. Automatic Triggering: Run after each NPM types release
2. Version Detection: Automatically detect current and previous versions from git tags
3. Build Integration: Build actual TypeScript types from the repository
4. PR Creation: Generate draft pull requests with the changelog
5. Human Review: Allow maintainers to review and enhance before merging

Benefits for Extension Developers

Clear Breaking Change Visibility

Extension developers can immediately see:

• What APIs were removed
• What signatures changed
• How to migrate their code

Migration Planning

With clear documentation of additions and changes, developers can:

• Plan updates around breaking changes
• Adopt new features when ready
• Understand version compatibility

Historical Reference

The cumulative docs/API-CHANGELOG.md provides:

• Complete API evolution history
• Context for design decisions
• Migration guides for major versions

Example Extension Migration

Before (v1.29.0)

// Old code using queuePrompt
const result = await api.queuePrompt(workflow);
console.log('Queued:', result.prompt_id);

After (v1.30.2)

// New code using queuePromptAsync with priority
const result = await api.queuePromptAsync(workflow, { priority: 1 });
console.log('Queued:', result.prompt_id, 'Position:', result.number);

Snapshot Structure

The JSON snapshots contain structured representations of:

{
  "types": { /* Type aliases */ },
  "interfaces": { /* Interface definitions with members */ },
  "enums": { /* Enum values */ },
  "functions": { /* Exported functions */ },
  "classes": { /* Class definitions with methods */ },
  "constants": { /* Exported constants */ }
}

Each entry includes:

• Name: Identifier
• Kind: Type of declaration
• Members/Methods: Properties and functions
• Types: Parameter and return types
• Visibility: Public/private/protected modifiers
• Optional: Whether parameters/properties are optional

Comparison Algorithm

The comparison script:

1. Categorizes changes into breaking, additions, and modifications
2. Detects breaking changes:
   • Removed interfaces, classes, functions
   • Removed methods or properties
   • Changed method signatures
   • Changed return types
   • Removed enum values
3. Tracks additions:
   • New interfaces, classes, types
   • New methods and properties
   • New enum values
4. Identifies modifications:
   • Type changes
   • Optionality changes
   • Signature changes

Future Enhancements

Planned improvements include:

• LLM Enhancement: Use AI to generate better descriptions and migration guides
• Email Notifications: Alert developers on mailing list for major changes
• Release Notes Integration: Auto-include in GitHub releases
• Deprecation Tracking: Mark APIs as deprecated before removal
• Example Code: Generate migration code snippets automatically

Conclusion

This automated system ensures:

• ✅ Zero manual effort for changelog generation
• ✅ Consistent documentation format
• ✅ Clear breaking change visibility
• ✅ Historical API evolution tracking
• ✅ Better extension developer experience