Backport Management

Backport Management

Cherry-pick backport management for Comfy-Org/ComfyUI_frontend stable release branches.

Quick Start

1. Discover — Collect candidates from Slack bot + git log gap, then reconcile both lists (reference/discovery.md)
2. Pre-filter by path — Auto-skip PRs whose changed files are entirely under apps/website/, browser_tests/, .github/, packages/design-system/, packages/{cloud,registry}-types/, .claude/, docs/. Don't read PR bodies for these — they don't ship to core ComfyUI users (reference/analysis.md)
3. Verify target file existence — For each surviving candidate, run git cat-file -e origin/$TARGET:$path for primary changed files. If they don't exist on the target, auto-mark SKIP with reason feature-not-on-branch
4. Tiered triage — Bucket into Tier 1 (core editor must-haves), Tier 2 (cloud-distribution only), Tier 3 (skip) before reviewing individually (reference/analysis.md)
5. Analyze — Categorize remaining MUST/SHOULD, check deps (reference/analysis.md)
6. Human Review — Present candidates in batches for interactive approval, with tier context attached (see Interactive Approval Flow)
7. Plan — Order by dependency (leaf fixes first), group into waves per branch
8. Test-then-resolve dry-run — Classify clean vs conflict before committing time (reference/execution.md)
9. Execute — Label-driven automation for clean PRs → worktree fallback for conflicts (reference/execution.md)
10. Public-API conflict review — If conflict resolution touches a public LiteGraph callback, extension API, or node.* method, consult oracle for compat-regression review BEFORE pushing (reference/execution.md)
11. Verify — Per-PR validation (typecheck + targeted tests + lint on changed files) AND per-wave verification (full typecheck + test:unit on branch HEAD)
12. Log & Report — Generate session report + author accountability report + Slack status update (reference/logging.md)

System Context

CI Safety Rules

NEVER merge a backport PR without all CI checks passing. This applies to both automation-created and manual cherry-pick PRs.

• Automation PRs: The pr-backport.yaml workflow now enables gh pr merge --auto --squash, so clean PRs auto-merge once CI passes. Monitor with polling (gh pr list --base TARGET_BRANCH --state open). Do not intervene unless CI fails.
• Manual cherry-pick PRs: After gh pr create, wait for CI before merging. Poll with gh pr checks $PR --watch or use a sleep+check loop. Only merge after all checks pass.
• CI failures: DO NOT use --admin to bypass failing CI. Analyze the failure, present it to the user with possible causes (test backported without implementation, missing dependency, flaky test), and let the user decide the next step.

Branch Scope Rules

Critical: Match PRs to the correct target branches.

What Goes Where

Both core + cloud:

• App mode PRs — app mode is NOT cloud-only
• Firebase auth PRs — Firebase auth is on core for API nodes
• Payment redirect PRs — payment infrastructure shared
• Bug fixes touching shared components

Cloud-only (skip for core):

• Team workspaces
• Cloud queue virtualization
• Hide API key login
• Cloud-specific UI behind cloud feature flags

⚠️ NEVER backport cloud-only PRs to core/* branches. But do NOT assume "app mode" or "Firebase" = cloud-only. Check the actual files changed.

⚠️ Gotchas (Learn from Past Sessions)

Use gh api for Labels — NOT gh pr edit

gh pr edit --add-label triggers Projects Classic deprecation errors. Always use:

gh api repos/Comfy-Org/ComfyUI_frontend/issues/$PR/labels \
  -f "labels[]=needs-backport" -f "labels[]=TARGET_BRANCH"

Automation Over-Reports Conflicts

The pr-backport.yaml action reports more conflicts than reality. git cherry-pick -m 1 with git auto-merge handles many cases the automation can't. Always attempt manual cherry-pick before skipping.

Never Skip Based on Conflict File Count

12 or 27 conflicting files can be trivial (snapshots, new files). Categorize conflicts first, then decide. See Conflict Triage below.

Accept-Theirs Can Produce Broken Hybrids

When a PR rewrites a component (e.g., PrimeVue → Reka UI), the accept-theirs regex produces a broken mix of old and new code. The template may reference new APIs while the script still has old imports, or vice versa.

Detection: Content conflicts with 4+ conflict markers in a single .vue file, especially when imports change between component libraries.

Fix: Instead of accept-theirs regex, use git show MERGE_SHA:path/to/file > path/to/file to get the complete correct version from the merge commit on main. This bypasses the conflict entirely.

Cherry-Picks Can Reference Missing Dependencies

When PR A on main depends on code introduced by PR B (which was merged before A), cherry-picking A brings in code that references B's additions. The cherry-pick succeeds but the branch is broken.

Common pattern: Composables, component files, or type definitions introduced by an earlier PR and used by the cherry-picked PR.

Detection: pnpm typecheck fails with "Cannot find module" or "is not defined" errors after cherry-pick.

Fix: Use git show MERGE_SHA:path/to/missing/file > path/to/missing/file to bring the missing files from main. Always verify with typecheck.

Use --no-verify for Worktree Pushes

Husky hooks fail in worktrees (can't find lint-staged config). Always use git push --no-verify and git commit --no-verify when working in /tmp/ worktrees.

Automation Success Varies Wildly by Branch

In the 2026-04-06 session: core/1.42 got 18/26 auto-PRs, cloud/1.42 got only 1/25. The cloud branch has more divergence. Always plan for manual fallback — don't assume automation will handle most PRs.

Cherry-Picked Tests Can Reference Files Added By Earlier Unbackported PRs

A common conflict: PR A on main modifies a test file that was added on main by an earlier PR B (not backported to the target). The cherry-pick of A reports "modify/delete" on B's test file because the file doesn't exist on the target. Adding the new file would smuggle in B's test scaffolding without B's runtime changes.

Detection: Conflict says deleted in HEAD and modified in <PR>. Verify with:

git log --diff-filter=A --oneline origin/main -- path/to/test.ts

If the introducing commit is not on the target branch, the test file isn't a real prerequisite for the runtime fix.

Fix: git rm the test file (drop it from the backport). Document in the commit body which PR introduced it on main and why dropping it is safe. The runtime fix itself usually doesn't depend on these tests — coverage exists at the integration layer.

Backport-Only Compatibility Shims

When a PR's mechanism relies on changes upstream that aren't on the older branch, a literal cherry-pick can recreate the original bug for any consumer still using the old contract. This is most dangerous for public LiteGraph callbacks, extension APIs, and node.* methods that custom-node packages depend on.

Real example (#11541, core/1.43 backport): The PR removed LGraphNode.vue's legacy handled === true sync-return check from handleDrop, replacing it with await node.onDragDrop(event, true). Safe on main because all in-repo onDragDrop handlers had migrated to participate in the new claimEvent flag. On core/1.43, onDragDrop is a public callback — custom-node packages with synchronous onDragDrop returning true would no longer have their event claimed, recreating the duplicate-node-creation bug the PR was fixing.

Detection: The PR's diff modifies a file that is part of a public extension API surface. Look for:

• node.onXxx callback assignments
• Methods on LGraphNode, LGraphCanvas, LGraph, Subgraph
• Public exports from src/lib/litegraph/
• Type changes affecting litegraph-augmentation.d.ts

Fix: Add a backport-only compatibility shim that preserves the old contract while keeping the new fix. Document it explicitly in the commit body under a ## Backport-only compatibility fix heading. Consult oracle for review before pushing — a bad shim is worse than no fix.

Conflict Triage

Always categorize before deciding to skip. High conflict count ≠ hard conflicts.

# Accept theirs for content conflicts
import re
pattern = r'<<<<<<< HEAD\n(.*?)=======\n(.*?)>>>>>>> [^\n]+\n?'
content = re.sub(pattern, r'\2', content, flags=re.DOTALL)

Escalation Triggers (Flag for Human)

• Package.json/lockfile changes → skip on stable (transitive dep regression risk)
• Core type definition changes → requires human judgment
• Business logic conflicts (not just imports/exports) → requires domain knowledge
• Admin-merged conflict resolutions → get human review of the resolution before continuing the wave