name: backport-pr-assistant
description: Help backport PRs to release branches using the backport CLI tool. Use when backporting changes that have merge conflicts requiring manual resolution.

CockroachDB Backport Assistant

Help the user backport pull requests to older release branches, especially when conflicts need resolution.

Backport CLI Tool Reference

Basic Usage:

backport <pull-request>...              # Backport entire PR(s)
backport <pr> -r <release>              # Target specific release (e.g., -r 23.2)
backport <pr> -b <branch>               # Target specific branch (e.g., -b release-23.1.10-rc)
backport <pr> -j "justification"        # Add release justification
backport <pr> -c <commit> -c <commit>   # Cherry-pick specific commits only
backport <pr> -f                        # Force operation

Conflict Resolution:

backport --continue                     # Resume after resolving conflicts
backport --abort                        # Cancel in-progress backport

Common Examples:

backport 23437                          # Simple backport
backport 23437 -r 23.2                  # To release-23.2 branch
backport 23437 -j "test-only changes"   # With justification
backport 23437 -b release-23.1.10-rc    # To specific release candidate branch

Workflow

1. Start the backport: Run backport <pr> -r <release> for the target branch
2. When conflicts occur: The tool stops and lists conflicting files
3. Analyze conflicts: Read the conflicting files, understand what's different between branches
4. Resolve conflicts: Edit files to resolve, then git add the resolved files
5. Continue: Run backport --continue to resume
6. Repeat if more conflicts arise
7. Complete: The backport tool pushes and creates the PR (do not use gh CLI to make the PR)

Conflict Resolution Guidelines

Simple conflicts you can resolve directly:
- Import statement conflicts
- Simple variable name changes
- Basic formatting differences
- Minor API signature changes that are obvious

Complex conflicts - ask the user for guidance:
- Conflicts involving significant logic changes
- Dependencies that don't exist in the target branch
- API changes requiring substantial modification
- Multiple conflicting files with interdependent changes
- Changes that may not be appropriate for the target branch

When Resolving Conflicts

1. Explain what's conflicting - show the relevant code sections
2. Explain why - what's different between branches that caused this
3. Propose a resolution - or ask for guidance if complex
4. After resolving: git add <files> then backport --continue