backport-pr-assistant

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