[refactor] Clean up API changelog implementation

- Remove demo-snapshots folder
- Merge workflow documentation into main workflows README
- Convert scripts to TypeScript (.js → .ts)
- Revert eslint.config.ts changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
snomiao
2025-11-10 09:35:35 +00:00
parent e36e25ebd6
commit 794829db6d
13 changed files with 227 additions and 1139 deletions

View File

@@ -1,234 +0,0 @@
# Manual API Changelog Generation
This workflow allows you to generate API changelogs by comparing any two versions of the ComfyUI Frontend package.
## Usage
### Via GitHub Actions UI
1. Go to **Actions** tab in the repository
2. Select **Manual API Changelog Generation** from the workflows list
3. Click **Run workflow** button
4. Fill in the inputs:
- **Previous version**: The earlier version (e.g., `1.29.0` or `v1.29.0`)
- **Current version**: The later version (e.g., `1.30.2` or `v1.30.2`)
- **Create PR**: Check this to automatically create a pull request with the changelog
### Via GitHub CLI
```bash
# Basic usage - just generate changelog
gh workflow run manual-api-changelog.yaml \
-f from_version=1.29.0 \
-f to_version=1.30.2 \
-f create_pr=false
# Generate changelog and create PR
gh workflow run manual-api-changelog.yaml \
-f from_version=1.29.0 \
-f to_version=1.30.2 \
-f create_pr=true
```
## What It Does
1. **Validates Inputs**: Checks that version formats are valid (X.Y.Z) and tags exist
2. **Builds Both Versions**: Checks out each version tag, installs dependencies, and builds TypeScript types
3. **Generates Snapshots**: Creates structured JSON snapshots of the public API surface for each version
4. **Compares APIs**: Analyzes differences and categorizes as:
- ⚠️ **Breaking changes** (removals, signature changes)
-**Additions** (new interfaces, methods, properties)
- 🔄 **Modifications** (non-breaking changes)
5. **Uploads Artifact**: Saves the changelog and snapshots as a workflow artifact (90-day retention)
6. **Creates PR** (optional): Generates a draft PR to update `docs/API-CHANGELOG.md`
## Output
### Workflow Artifacts
Every run produces an artifact containing:
- `CHANGELOG-{from}-to-{to}.md` - Human-readable changelog
- `from.json` - API snapshot of the earlier version
- `to.json` - API snapshot of the later version
**Retention**: 90 days
### Pull Request (Optional)
If `create_pr` is enabled and changes are detected:
- Creates a draft PR with title: `[docs] API Changelog: v{from} → v{to}`
- Updates `docs/API-CHANGELOG.md` with the new changelog entry
- Includes detailed metadata and review instructions
- Labeled with `documentation`
## Example Changelog Output
```markdown
## v1.30.2 (2025-11-04)
Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface.
### ✨ Additions
**Type Aliases**
- `WorkflowId`
**Interfaces**
- `ExtensionMetadata`
- Members: `id`, `name`, `version`, `description`
### 🔄 Modifications
> **Note**: Some modifications may be breaking changes.
**Interfaces**
- `ComfyApi`
- ✨ Added member: `queuePromptAsync`
- ✨ Added member: `cancelPrompt`
- ⚠️ **Breaking**: Removed member: `queuePrompt`
**Enums**
- `NodeStatus`
- ✨ Added enum value: `ERROR`
- ✨ Added enum value: `COMPLETED`
```
## Use Cases
### 1. Generate Changelog for Missed Releases
If the automatic workflow failed or was skipped for a release:
```bash
gh workflow run manual-api-changelog.yaml \
-f from_version=1.28.0 \
-f to_version=1.29.0 \
-f create_pr=true
```
### 2. Compare Non-Adjacent Versions
To see cumulative changes across multiple releases:
```bash
gh workflow run manual-api-changelog.yaml \
-f from_version=1.25.0 \
-f to_version=1.30.2 \
-f create_pr=false
```
### 3. Test Upcoming Changes
Compare current `main` branch against the latest release (requires creating a temporary tag):
```bash
# Create temporary tag for current main
git tag v1.31.0-preview
git push origin v1.31.0-preview
# Run comparison
gh workflow run manual-api-changelog.yaml \
-f from_version=1.30.2 \
-f to_version=1.31.0-preview \
-f create_pr=false
# Clean up temporary tag
git tag -d v1.31.0-preview
git push origin :refs/tags/v1.31.0-preview
```
### 4. Audit Historical Changes
Generate changelogs for documentation purposes:
```bash
# Compare multiple version pairs
for from in 1.26.0 1.27.0 1.28.0 1.29.0; do
to=$(echo "$from" | awk -F. '{print $1"."$2+1".0"}')
gh workflow run manual-api-changelog.yaml \
-f from_version=$from \
-f to_version=$to \
-f create_pr=false
done
```
## Validation
The workflow validates:
- ✅ Version format matches semantic versioning (X.Y.Z)
- ✅ Both version tags exist in the repository
- ✅ Tags reference valid commits with buildable code
If validation fails, the workflow exits early with a clear error message.
## Limitations
- **Tag requirement**: Both versions must have corresponding `vX.Y.Z` git tags
- **Build requirement**: Both versions must have functional build processes
- **Type files**: Requires `dist/index.d.ts` to exist after building
- **Scripts**: Requires `scripts/snapshot-api.js` and `scripts/compare-api-snapshots.js` to be present
## Related Workflows
- **[Release API Changelogs](.github/workflows/release-api-changelogs.yaml)**: Automatic changelog generation triggered by NPM releases
- **[Release NPM Types](.github/workflows/release-npm-types.yaml)**: Publishes type definitions and triggers automatic changelog
## Troubleshooting
### "Tag does not exist" error
Ensure the version exists as a git tag:
```bash
git tag -l 'v*' | grep 1.29.0
```
If missing, the version may not have been released yet.
### "Build failed" error
Check that the version can be built successfully:
```bash
git checkout v1.29.0
pnpm install
pnpm build:types
```
### No changes detected
If the workflow reports no changes but you expect some:
1. Check the artifact snapshots to verify they're different
2. Ensure you're comparing the correct versions
3. Review the comparison script logic in `scripts/compare-api-snapshots.js`
### PR not created
PR creation requires:
- `create_pr` input set to `true`
- Significant changes detected (more than just headers)
- `PR_GH_TOKEN` secret configured with appropriate permissions
## Security
- **Permissions**: Workflow requires `contents: write` and `pull-requests: write`
- **Token**: Uses `secrets.PR_GH_TOKEN` for PR creation
- **Isolation**: Each workflow run uses a unique concurrency group
- **Artifacts**: Retained for 90 days, accessible to repository collaborators
## Monitoring
View workflow runs:
```bash
gh run list --workflow=manual-api-changelog.yaml
```
View specific run details:
```bash
gh run view <run-id>
```
Download artifacts:
```bash
gh run download <run-id>
```

View File

@@ -19,3 +19,214 @@ Workflow files follow a consistent naming pattern: `<prefix>-<descriptive-name>.
Each workflow file contains comments explaining its purpose, triggers, and behavior. For specific details about what each workflow does, refer to the comments at the top of each `.yaml` file.
For GitHub Actions documentation, see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows).
## Manual API Changelog Generation
The `manual-api-changelog.yaml` workflow allows you to generate API changelogs by comparing any two versions of the ComfyUI Frontend package.
### Usage
#### Via GitHub Actions UI
1. Go to **Actions** tab in the repository
2. Select **Manual API Changelog Generation** from the workflows list
3. Click **Run workflow** button
4. Fill in the inputs:
- **Previous version**: The earlier version (e.g., `1.29.0` or `v1.29.0`)
- **Current version**: The later version (e.g., `1.30.2` or `v1.30.2`)
- **Create PR**: Check this to automatically create a pull request with the changelog
#### Via GitHub CLI
```bash
# Basic usage - just generate changelog
gh workflow run manual-api-changelog.yaml \
-f from_version=1.29.0 \
-f to_version=1.30.2 \
-f create_pr=false
# Generate changelog and create PR
gh workflow run manual-api-changelog.yaml \
-f from_version=1.29.0 \
-f to_version=1.30.2 \
-f create_pr=true
```
### What It Does
1. **Validates Inputs**: Checks that version formats are valid (X.Y.Z) and tags exist
2. **Builds Both Versions**: Checks out each version tag, installs dependencies, and builds TypeScript types
3. **Generates Snapshots**: Creates structured JSON snapshots of the public API surface for each version
4. **Compares APIs**: Analyzes differences and categorizes as:
- ⚠️ **Breaking changes** (removals, signature changes)
-**Additions** (new interfaces, methods, properties)
- 🔄 **Modifications** (non-breaking changes)
5. **Uploads Artifact**: Saves the changelog and snapshots as a workflow artifact (90-day retention)
6. **Creates PR** (optional): Generates a draft PR to update `docs/API-CHANGELOG.md`
### Output
#### Workflow Artifacts
Every run produces an artifact containing:
- `CHANGELOG-{from}-to-{to}.md` - Human-readable changelog
- `from.json` - API snapshot of the earlier version
- `to.json` - API snapshot of the later version
**Retention**: 90 days
#### Pull Request (Optional)
If `create_pr` is enabled and changes are detected:
- Creates a draft PR with title: `[docs] API Changelog: v{from} → v{to}`
- Updates `docs/API-CHANGELOG.md` with the new changelog entry
- Includes detailed metadata and review instructions
- Labeled with `documentation`
### Example Changelog Output
```markdown
## v1.30.2 (2025-11-04)
Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface.
### ✨ Additions
**Type Aliases**
- `WorkflowId`
**Interfaces**
- `ExtensionMetadata`
- Members: `id`, `name`, `version`, `description`
### 🔄 Modifications
> **Note**: Some modifications may be breaking changes.
**Interfaces**
- `ComfyApi`
- ✨ Added member: `queuePromptAsync`
- ✨ Added member: `cancelPrompt`
- ⚠️ **Breaking**: Removed member: `queuePrompt`
**Enums**
- `NodeStatus`
- ✨ Added enum value: `ERROR`
- ✨ Added enum value: `COMPLETED`
```
### Use Cases
#### 1. Generate Changelog for Missed Releases
If the automatic workflow failed or was skipped for a release:
```bash
gh workflow run manual-api-changelog.yaml \
-f from_version=1.28.0 \
-f to_version=1.29.0 \
-f create_pr=true
```
#### 2. Compare Non-Adjacent Versions
To see cumulative changes across multiple releases:
```bash
gh workflow run manual-api-changelog.yaml \
-f from_version=1.25.0 \
-f to_version=1.30.2 \
-f create_pr=false
```
#### 3. Test Upcoming Changes
Compare current `main` branch against the latest release (requires creating a temporary tag):
```bash
# Create temporary tag for current main
git tag v1.31.0-preview
git push origin v1.31.0-preview
# Run comparison
gh workflow run manual-api-changelog.yaml \
-f from_version=1.30.2 \
-f to_version=1.31.0-preview \
-f create_pr=false
# Clean up temporary tag
git tag -d v1.31.0-preview
git push origin :refs/tags/v1.31.0-preview
```
#### 4. Audit Historical Changes
Generate changelogs for documentation purposes:
```bash
# Compare multiple version pairs
for from in 1.26.0 1.27.0 1.28.0 1.29.0; do
to=$(echo "$from" | awk -F. '{print $1"."$2+1".0"}')
gh workflow run manual-api-changelog.yaml \
-f from_version=$from \
-f to_version=$to \
-f create_pr=false
done
```
### Validation
The workflow validates:
- ✅ Version format matches semantic versioning (X.Y.Z)
- ✅ Both version tags exist in the repository
- ✅ Tags reference valid commits with buildable code
If validation fails, the workflow exits early with a clear error message.
### Limitations
- **Tag requirement**: Both versions must have corresponding `vX.Y.Z` git tags
- **Build requirement**: Both versions must have functional build processes
- **Type files**: Requires `dist/index.d.ts` to exist after building
- **Scripts**: Requires `scripts/snapshot-api.ts` and `scripts/compare-api-snapshots.ts` to be present
### Related Workflows
- **[Release API Changelogs](.github/workflows/release-api-changelogs.yaml)**: Automatic changelog generation triggered by NPM releases
- **[Release NPM Types](.github/workflows/release-npm-types.yaml)**: Publishes type definitions and triggers automatic changelog
### Troubleshooting
#### "Tag does not exist" error
Ensure the version exists as a git tag:
```bash
git tag -l 'v*' | grep 1.29.0
```
If missing, the version may not have been released yet.
#### "Build failed" error
Check that the version can be built successfully:
```bash
git checkout v1.29.0
pnpm install
pnpm build:types
```
#### No changes detected
If the workflow reports no changes but you expect some:
1. Check the artifact snapshots to verify they're different
2. Ensure you're comparing the correct versions
3. Review the comparison script logic in `scripts/compare-api-snapshots.ts`
#### PR not created
PR creation requires:
- `create_pr` input set to `true`
- Significant changes detected (more than just headers)
- `PR_GH_TOKEN` secret configured with appropriate permissions

View File

@@ -98,7 +98,7 @@ jobs:
run: |
# Copy scripts to temporary location
mkdir -p /tmp/api-changelog-scripts
cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/
cp scripts/snapshot-api.ts scripts/compare-api-snapshots.ts /tmp/api-changelog-scripts/
- name: Build and snapshot TO version
run: |
@@ -107,13 +107,13 @@ jobs:
# Restore scripts
mkdir -p scripts
cp /tmp/api-changelog-scripts/*.js scripts/
cp /tmp/api-changelog-scripts/*.ts scripts/
pnpm install --frozen-lockfile
pnpm build:types
# Generate snapshot
node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-to.json
node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > /tmp/api-snapshots-to.json
echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.to_version }}"
@@ -124,13 +124,13 @@ jobs:
# Restore scripts
mkdir -p scripts
cp /tmp/api-changelog-scripts/*.js scripts/
cp /tmp/api-changelog-scripts/*.ts scripts/
pnpm install --frozen-lockfile
pnpm build:types
# Generate snapshot
node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-from.json
node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > /tmp/api-snapshots-from.json
echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.from_version }}"
@@ -140,7 +140,7 @@ jobs:
# Restore scripts
mkdir -p scripts
cp /tmp/api-changelog-scripts/*.js scripts/
cp /tmp/api-changelog-scripts/*.ts scripts/
# Copy snapshots to working directory
cp /tmp/api-snapshots-from.json .api-snapshots/from.json
@@ -153,7 +153,7 @@ jobs:
GIT_REF=$(git rev-parse ${{ steps.validate_versions.outputs.to_tag }})
# Run the comparison script
CHANGELOG_OUTPUT=$(node scripts/compare-api-snapshots.js \
CHANGELOG_OUTPUT=$(node --loader tsx scripts/compare-api-snapshots.ts \
.api-snapshots/from.json \
.api-snapshots/to.json \
${{ steps.validate_versions.outputs.from_version }} \

View File

@@ -88,7 +88,7 @@ jobs:
mkdir -p .api-snapshots
# Generate snapshot of current types
node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/current.json
node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > .api-snapshots/current.json
echo "Current API snapshot created"
@@ -97,7 +97,7 @@ jobs:
run: |
# Copy scripts to temporary location to use with previous version
mkdir -p /tmp/api-changelog-scripts
cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/
cp scripts/snapshot-api.ts scripts/compare-api-snapshots.ts /tmp/api-changelog-scripts/
- name: Checkout previous version
if: steps.previous_version.outputs.tag != ''
@@ -110,7 +110,7 @@ jobs:
# Restore scripts
mkdir -p scripts
cp /tmp/api-changelog-scripts/*.js scripts/
cp /tmp/api-changelog-scripts/*.ts scripts/
- name: Build previous types
if: steps.previous_version.outputs.tag != ''
@@ -122,7 +122,7 @@ jobs:
if: steps.previous_version.outputs.tag != ''
run: |
# Generate snapshot of previous types
node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/previous.json
node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > .api-snapshots/previous.json
echo "Previous API snapshot created"
@@ -130,7 +130,7 @@ jobs:
if: steps.previous_version.outputs.tag != ''
run: |
# Remove copied scripts to avoid conflicts
rm -f scripts/snapshot-api.js scripts/compare-api-snapshots.js
rm -f scripts/snapshot-api.ts scripts/compare-api-snapshots.ts
git checkout -
git stash pop || true
@@ -146,7 +146,7 @@ jobs:
# Run the comparison script
if [ -f .api-snapshots/previous.json ]; then
node scripts/compare-api-snapshots.js \
node --loader tsx scripts/compare-api-snapshots.ts \
.api-snapshots/previous.json \
.api-snapshots/current.json \
${{ steps.previous_version.outputs.version }} \