mirror of https://github.com/Comfy-Org/ComfyUI_frontend.git synced 2026-02-22 15:54:09 +00:00

Files

Christian Byrne 3e2d62efb4 [CI] Auto-create release candidate branches for minor/major versions (#4777 )

2025-08-05 23:50:53 -07:00

20 KiB

Raw Blame History

Create Frontend Release

This command guides you through creating a comprehensive frontend release with semantic versioning analysis, automated change detection, security scanning, and multi-stage human verification.

Create a frontend release with version type: $ARGUMENTS

Expected format: Version increment type and optional description Examples:

patch - Bug fixes only
minor - New features, backward compatible
major - Breaking changes
prerelease - Alpha/beta/rc releases
patch "Critical security fixes" - With custom description
minor --skip-changelog - Skip automated changelog generation
minor --dry-run - Simulate release without executing

If no arguments provided, the command will always perform prerelease if the current version is prerelease, or patch in other cases. This command will never perform minor or major releases without explicit direction.

Prerequisites

Before starting, ensure:

You have push access to the repository
GitHub CLI (gh) is authenticated
You're on a clean main branch working tree
All intended changes are merged to main
You understand the scope of changes being released

Critical Checks Before Starting

1. Check Current Version Status

# Get current version and check if it's a pre-release
CURRENT_VERSION=$(node -p "require('./package.json').version")
if [[ "$CURRENT_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+- ]]; then
  echo "⚠️  Current version $CURRENT_VERSION is a pre-release"
  echo "Consider releasing stable (e.g., 1.24.0-1 → 1.24.0) first"
fi

2. Find Last Stable Release

# Get last stable release tag (no pre-release suffix)
LAST_STABLE=$(git tag -l "v*" | grep -v "\-" | sort -V | tail -1)
echo "Last stable release: $LAST_STABLE"

Configuration Options

Environment Variables:

RELEASE_SKIP_SECURITY_SCAN=true - Skip security audit
RELEASE_AUTO_APPROVE=true - Skip some confirmation prompts
RELEASE_DRY_RUN=true - Simulate release without executing

Release Process

Step 1: Environment Safety Check

Verify clean working directory:
```
git status --porcelain
```
Confirm on main branch:
```
git branch --show-current
```
Pull latest changes:
```
git pull origin main
```
Check GitHub CLI authentication:
```
gh auth status
```
Verify npm/PyPI publishing access (dry run)
CONFIRMATION REQUIRED: Environment ready for release?

Step 2: Analyze Recent Changes

Get current version from package.json

IMPORTANT: Determine correct base for comparison:

# If current version is pre-release, use last stable release
if [[ "$CURRENT_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+- ]]; then
  BASE_TAG=$LAST_STABLE
else
  BASE_TAG=$(git describe --tags --abbrev=0)
fi

Find commits since base release (CRITICAL: use --first-parent):

git log ${BASE_TAG}..HEAD --oneline --no-merges --first-parent

Count total commits:

COMMIT_COUNT=$(git log ${BASE_TAG}..HEAD --oneline --no-merges --first-parent | wc -l)
echo "Found $COMMIT_COUNT commits since $BASE_TAG"

Analyze commits for:
- Breaking changes (BREAKING CHANGE, !, feat())
- New features (feat:, feature:)
- Bug fixes (fix:, bugfix:)
- Documentation changes (docs:)
- Dependency updates

VERIFY PR TARGET BRANCHES:

# Get merged PRs and verify they were merged to main
gh pr list --state merged --limit 50 --json number,title,baseRefName,mergedAt | \
  jq -r '.[] | select(.baseRefName == "main") | "\(.number): \(.title)"'

HUMAN ANALYSIS: Review change summary and verify scope

Step 3: Version Preview

Version Preview:

Current: ${CURRENT_VERSION}
Proposed: Show exact version number
CONFIRMATION REQUIRED: Proceed with version X.Y.Z?

Step 4: Security and Dependency Audit

Run security audit:
```
npm audit --audit-level moderate
```
Check for known vulnerabilities in dependencies

Scan for hardcoded secrets or credentials:

git log -p ${BASE_TAG}..HEAD | grep -iE "(password|key|secret|token)" || echo "No sensitive data found"

Verify no sensitive data in recent commits
SECURITY REVIEW: Address any critical findings before proceeding?

Step 5: Pre-Release Testing

Run complete test suite:

npm run test:unit
npm run test:component

Run type checking:
```
npm run typecheck
```

Run linting (may have issues with missing packages):

npm run lint || echo "Lint issues - verify if critical"

Test build process:
```
npm run build
npm run build:types
```
QUALITY GATE: All tests and builds passing?

Step 6: Breaking Change Analysis

Analyze API changes in:
- Public TypeScript interfaces
- Extension APIs
- Component props
- CLAUDE.md guidelines
Check for:
- Removed public functions/classes
- Changed function signatures
- Deprecated feature removals
- Configuration changes
Generate breaking change summary
COMPATIBILITY REVIEW: Breaking changes documented and justified?

Step 7: Analyze Dependency Updates

Check significant dependency updates:

# Extract all dependency changes for major version bumps
OTHER_DEP_CHANGES=""

# Compare major dependency versions (you can extend this list)
MAJOR_DEPS=("vue" "vite" "@vitejs/plugin-vue" "typescript" "pinia")

for dep in "${MAJOR_DEPS[@]}"; do
  PREV_VER=$(echo "$PREV_PACKAGE_JSON" | grep -o "\"$dep\": \"[^\"]*\"" | grep -o '[0-9][^"]*' | head -1 || echo "")
  CURR_VER=$(echo "$CURRENT_PACKAGE_JSON" | grep -o "\"$dep\": \"[^\"]*\"" | grep -o '[0-9][^"]*' | head -1 || echo "")

  if [ "$PREV_VER" != "$CURR_VER" ] && [ -n "$PREV_VER" ] && [ -n "$CURR_VER" ]; then
    # Check if it's a major version change
    PREV_MAJOR=$(echo "$PREV_VER" | cut -d. -f1 | sed 's/[^0-9]//g')
    CURR_MAJOR=$(echo "$CURR_VER" | cut -d. -f1 | sed 's/[^0-9]//g')

    if [ "$PREV_MAJOR" != "$CURR_MAJOR" ]; then
      OTHER_DEP_CHANGES="${OTHER_DEP_CHANGES}\n- **${dep}**: ${PREV_VER} → ${CURR_VER} (Major version change)"
    fi
  fi
done

Step 8: Generate Comprehensive Release Notes

Extract commit messages since base release:

git log ${BASE_TAG}..HEAD --oneline --no-merges --first-parent > commits.txt

CRITICAL: Verify PR inclusion by checking merge location:

# For each significant PR mentioned, verify it's on main
for PR in ${SIGNIFICANT_PRS}; do
  COMMIT=$(gh pr view $PR --json mergeCommit -q .mergeCommit.oid)
  git branch -r --contains $COMMIT | grep -q "origin/main" || \
    echo "WARNING: PR #$PR not on main branch!"
done

Create comprehensive release notes including:
- Version Change: Show version bump details
- Changelog grouped by type:
  - 🚀 Features (feat:)
  - 🐛 Bug Fixes (fix:)
  - 💥 Breaking Changes (BREAKING CHANGE)
  - 📚 Documentation (docs:)
  - 🔧 Maintenance (chore:, refactor:)
  - ⬆️ Dependencies (deps:, dependency updates)
    - Litegraph Changes (if version updated):
      - 🚀 Features: ${LITEGRAPH_FEATURES}
      - 🐛 Bug Fixes: ${LITEGRAPH_FIXES}
      - 💥 Breaking Changes: ${LITEGRAPH_BREAKING}
      - 🔧 Other Changes: ${LITEGRAPH_OTHER}
    - Other Major Dependencies: ${OTHER_DEP_CHANGES}
- Include PR numbers and links
- Add issue references (Fixes #123)

Save release notes:

# Save release notes for PR and GitHub release
echo "$RELEASE_NOTES" > release-notes-${NEW_VERSION}.md

CONTENT REVIEW: Release notes clear and comprehensive with dependency details?

Step 9: Create Version Bump PR

For standard version bumps (patch/minor/major):

# Trigger the workflow
gh workflow run version-bump.yaml -f version_type=${VERSION_TYPE}

# Workflow runs quickly - usually creates PR within 30 seconds
echo "Workflow triggered. Waiting for PR creation..."

For releasing a stable version:

Must manually create branch and update version:

git checkout -b version-bump-${NEW_VERSION}
# Edit package.json to remove pre-release suffix
git add package.json
git commit -m "${NEW_VERSION}"
git push origin version-bump-${NEW_VERSION}

Wait for PR creation (if using workflow) or create manually:

# For workflow-created PRs - wait and find it
sleep 30
# Look for PR from comfy-pr-bot (not github-actions)
PR_NUMBER=$(gh pr list --author comfy-pr-bot --limit 1 --json number --jq '.[0].number')

# Verify we got the PR
if [ -z "$PR_NUMBER" ]; then
  echo "PR not found yet. Checking recent PRs..."
  gh pr list --limit 5 --json number,title,author
fi

# For manual PRs
gh pr create --title "${NEW_VERSION}" \
  --body-file release-notes-${NEW_VERSION}.md \
  --label "Release"

Add required sections to PR body:

# Create PR body with release notes plus required sections
cat > pr-body.md << EOF
${RELEASE_NOTES}

## Breaking Changes
${BREAKING_CHANGES:-None}

## Testing Performed
- ✅ Full test suite (unit, component)
- ✅ TypeScript compilation
- ✅ Linting checks
- ✅ Build verification
- ✅ Security audit

## Distribution Channels
- GitHub Release (with dist.zip)
- PyPI Package (comfyui-frontend-package)
- npm Package (@comfyorg/comfyui-frontend-types)

## Post-Release Tasks
- [ ] Verify all distribution channels
- [ ] Update external documentation
- [ ] Monitor for issues
EOF

Update PR with enhanced description:

gh pr edit ${PR_NUMBER} --body-file pr-body.md

PR REVIEW: Version bump PR created and enhanced correctly?

Step 10: Critical Release PR Verification

CRITICAL: Verify PR has "Release" label:

gh pr view ${PR_NUMBER} --json labels | jq -r '.labels[].name' | grep -q "Release" || \
  echo "ERROR: Release label missing! Add it immediately!"

Check for update-locales commits:

# WARNING: update-locales may add [skip ci] which blocks release workflow!
gh pr view ${PR_NUMBER} --json commits | grep -q "skip ci" && \
  echo "WARNING: [skip ci] detected - release workflow may not trigger!"

Verify version number in package.json
Review all changed files
Ensure no unintended changes included
Wait for required PR checks:
```
gh pr checks ${PR_NUMBER} --watch
```
FINAL CODE REVIEW: Release label present and no [skip ci]?

Step 11: Pre-Merge Validation

Review Requirements: Release PRs require approval
Monitor CI checks - watch for update-locales
CRITICAL WARNING: If update-locales adds [skip ci], the release workflow won't trigger!
Check no new commits to main since PR creation
DEPLOYMENT READINESS: Ready to merge?

Step 12: Execute Release

FINAL CONFIRMATION: Merge PR to trigger release?
Merge the Release PR:
```
gh pr merge ${PR_NUMBER} --merge
```

IMMEDIATELY CHECK: Did release workflow trigger?

sleep 10
gh run list --workflow=release.yaml --limit=1

For Minor/Major Version Releases: The create-release-candidate-branch workflow will automatically:
- Create a core/x.yy branch for the PREVIOUS minor version
- Apply branch protection rules
- Document the feature freeze policy
```
# Monitor branch creation (for minor/major releases)
gh run list --workflow=create-release-candidate-branch.yaml --limit=1
```

If workflow didn't trigger due to [skip ci]:

echo "ERROR: Release workflow didn't trigger!"
echo "Options:"
echo "1. Create patch release (e.g., 1.24.1) to trigger workflow"
echo "2. Investigate manual release options"

If workflow triggered, monitor execution:

WORKFLOW_RUN_ID=$(gh run list --workflow=release.yaml --limit=1 --json databaseId --jq '.[0].databaseId')
gh run watch ${WORKFLOW_RUN_ID}

Step 13: Enhance GitHub Release

Wait for automatic release creation:

# Wait for release to be created
while ! gh release view v${NEW_VERSION} >/dev/null 2>&1; do
  echo "Waiting for release creation..."
  sleep 10
done

Enhance the GitHub release:

# Update release with our release notes
gh release edit v${NEW_VERSION} \
  --title "🚀 ComfyUI Frontend v${NEW_VERSION}" \
  --notes-file release-notes-${NEW_VERSION}.md \
  --latest

# Add any additional assets if needed
# gh release upload v${NEW_VERSION} additional-assets.zip

Verify release details:
```
gh release view v${NEW_VERSION}
```

Step 14: Verify Multi-Channel Distribution

GitHub Release:
```
gh release view v${NEW_VERSION} --json assets,body,createdAt,tagName
```
- ✅ Check release notes
- ✅ Verify dist.zip attachment
- ✅ Confirm release marked as latest (for main branch)

PyPI Package:

# Check PyPI availability (may take a few minutes)
for i in {1..10}; do
  if curl -s https://pypi.org/pypi/comfyui-frontend-package/json | jq -r '.releases | keys[]' | grep -q ${NEW_VERSION}; then
    echo "✅ PyPI package available"
    break
  fi
  echo "⏳ Waiting for PyPI package... (attempt $i/10)"
  sleep 30
done

npm Package:

# Check npm availability
for i in {1..10}; do
  if npm view @comfyorg/comfyui-frontend-types@${NEW_VERSION} version >/dev/null 2>&1; then
    echo "✅ npm package available"
    break
  fi
  echo "⏳ Waiting for npm package... (attempt $i/10)"
  sleep 30
done

DISTRIBUTION VERIFICATION: All channels published successfully?

Step 15: Post-Release Monitoring Setup

Monitor immediate release health:

# Check for immediate issues
gh issue list --label "bug" --state open --limit 5 --json title,number,createdAt

# Monitor download metrics (if accessible)
gh release view v${NEW_VERSION} --json assets --jq '.assets[].downloadCount'

Update documentation tracking:

cat > post-release-checklist.md << EOF
# Post-Release Checklist for v${NEW_VERSION}

## Immediate Tasks (Next 24 hours)
- [ ] Monitor error rates and user feedback
- [ ] Watch for critical issues
- [ ] Verify documentation is up to date
- [ ] Check community channels for questions

## Short-term Tasks (Next week)
- [ ] Update external integration guides
- [ ] Monitor adoption metrics
- [ ] Gather user feedback
- [ ] Plan next release cycle

## Long-term Tasks
- [ ] Analyze release process improvements
- [ ] Update release templates based on learnings
- [ ] Document any new patterns discovered

## Key Metrics to Track
- Download counts: GitHub, PyPI, npm
- Issue reports related to v${NEW_VERSION}
- Community feedback and adoption
- Performance impact measurements
EOF

Create release summary:

cat > release-summary-${NEW_VERSION}.md << EOF
# Release Summary: ComfyUI Frontend v${NEW_VERSION}

**Released:** $(date)
**Type:** ${VERSION_TYPE}
**Duration:** ~${RELEASE_DURATION} minutes
**Release Commit:** ${RELEASE_COMMIT}

## Metrics
- **Commits Included:** ${COMMITS_COUNT}
- **Contributors:** ${CONTRIBUTORS_COUNT}
- **Files Changed:** ${FILES_CHANGED}
- **Lines Added/Removed:** +${LINES_ADDED}/-${LINES_REMOVED}

## Distribution Status
- ✅ GitHub Release: Published
- ✅ PyPI Package: Available
- ✅ npm Types: Available

## Next Steps
- Monitor for 24-48 hours
- Address any critical issues immediately
- Plan next release cycle

## Files Generated
- \`release-notes-${NEW_VERSION}.md\` - Comprehensive release notes
- \`post-release-checklist.md\` - Follow-up tasks
EOF

RELEASE COMPLETION: All post-release setup completed?

Advanced Safety Features

Rollback Procedures

Pre-Merge Rollback:

# Close version bump PR and reset
gh pr close ${PR_NUMBER}
git reset --hard origin/main
git clean -fd

Post-Merge Rollback:

# Create immediate patch release with reverts
git revert ${RELEASE_COMMIT}
# Follow this command again with patch version

Emergency Procedures:

# Document incident
cat > release-incident-${NEW_VERSION}.md << EOF
# Release Incident Report

**Version:** ${NEW_VERSION}
**Issue:** [Describe the problem]
**Impact:** [Severity and scope]
**Resolution:** [Steps taken]
**Prevention:** [Future improvements]
EOF

# Contact package registries for critical issues
echo "For critical security issues, consider:"
echo "- PyPI: Contact support for package yanking"
echo "- npm: Use 'npm unpublish' within 72 hours"
echo "- GitHub: Update release with warning notes"

Quality Gates Summary

The command implements multiple quality gates:

🔒 Security Gate: Vulnerability scanning, secret detection
🧪 Quality Gate: Unit and component tests, linting, type checking
📋 Content Gate: Changelog accuracy, release notes quality
🔄 Process Gate: Release timing verification
✅ Verification Gate: Multi-channel publishing confirmation
📊 Monitoring Gate: Post-release health tracking

Common Scenarios

Scenario 1: Regular Feature Release

/project:create-frontend-release minor

Analyzes features since last release
Generates changelog automatically
Creates comprehensive release notes

Scenario 2: Critical Security Patch

/project:create-frontend-release patch "Security fixes for CVE-2024-XXXX"

Expedited security scanning
Enhanced monitoring setup

Scenario 3: Major Version with Breaking Changes

/project:create-frontend-release major

Comprehensive breaking change analysis
Migration guide generation

Scenario 4: Pre-release Testing

/project:create-frontend-release prerelease

Creates alpha/beta/rc versions
Draft release status
Python package specs require that prereleases use alpha/beta/rc as the preid

Common Issues and Solutions

Issue: Pre-release Version Confusion

Problem: Not sure whether to promote pre-release or create new version Solution:

Follow semver standards: a prerelease version is followed by a normal release. It should have the same major, minor, and patch versions as the prerelease.

Issue: Wrong Commit Count

Problem: Changelog includes commits from other branches Solution: Always use --first-parent flag with git log

Update: Sometimes update-locales doesn't add [skip ci] - always verify!

Issue: Missing PRs in Changelog

Problem: PR was merged to different branch Solution: Verify PR merge target with:

gh pr view ${PR_NUMBER} --json baseRefName

Issue: Incomplete Dependency Changelog

Problem: Litegraph or other dependency updates only show version bump, not actual changes Solution: The command now automatically:

Detects litegraph version changes between releases
Clones the litegraph repository temporarily
Extracts and categorizes changes between versions
Includes detailed litegraph changelog in release notes
Cleans up temporary files after analysis

Issue: Release Failed Due to [skip ci]

Problem: Release workflow didn't trigger after merge Prevention: Always avoid this scenario

Ensure that [skip ci] or similar flags are NOT in the HEAD commit message of the PR
- Push a new, empty commit to the PR
Always double-check this immediately before merging

Recovery Strategy:

Revert version in a new PR (e.g., 1.24.0 → 1.24.0-1)
Merge the revert PR
Run version bump workflow again
This creates a fresh PR without [skip ci] Benefits: Cleaner than creating extra version numbers

Key Learnings & Notes

PR Author: Version bump PRs are created by comfy-pr-bot, not github-actions
Workflow Speed: Version bump workflow typically completes in ~20-30 seconds
Update-locales Behavior: Inconsistent - sometimes adds [skip ci], sometimes doesn't
Recovery Options: Reverting version is cleaner than creating extra versions
Dependency Tracking: Command now automatically includes litegraph and major dependency changes in changelogs
Litegraph Integration: Temporary cloning of litegraph repo provides detailed change analysis between versions

20 KiB Raw Blame History