|
| 1 | +--- |
| 2 | +name: backport-pr-assistant |
| 3 | +description: Help backport PRs to release branches using the backport CLI tool. Use when backporting changes that have merge conflicts requiring manual resolution. |
| 4 | +--- |
| 5 | + |
| 6 | +# CockroachDB Backport Assistant |
| 7 | + |
| 8 | +Help the user backport pull requests to older release branches, especially when conflicts need resolution. |
| 9 | + |
| 10 | +## Backport CLI Tool Reference |
| 11 | + |
| 12 | +**Basic Usage:** |
| 13 | +```bash |
| 14 | +backport <pull-request>... # Backport entire PR(s) |
| 15 | +backport <pr> -r <release> # Target specific release (e.g., -r 23.2) |
| 16 | +backport <pr> -b <branch> # Target specific branch (e.g., -b release-23.1.10-rc) |
| 17 | +backport <pr> -j "justification" # Add release justification |
| 18 | +backport <pr> -c <commit> -c <commit> # Cherry-pick specific commits only |
| 19 | +backport <pr> -f # Force operation |
| 20 | +``` |
| 21 | + |
| 22 | +**Conflict Resolution:** |
| 23 | +```bash |
| 24 | +backport --continue # Resume after resolving conflicts |
| 25 | +backport --abort # Cancel in-progress backport |
| 26 | +``` |
| 27 | + |
| 28 | +**Common Examples:** |
| 29 | +```bash |
| 30 | +backport 23437 # Simple backport |
| 31 | +backport 23437 -r 23.2 # To release-23.2 branch |
| 32 | +backport 23437 -j "test-only changes" # With justification |
| 33 | +backport 23437 -b release-23.1.10-rc # To specific release candidate branch |
| 34 | +``` |
| 35 | + |
| 36 | +## Workflow |
| 37 | + |
| 38 | +1. **Start the backport**: Run `backport <pr> -r <release>` for the target branch |
| 39 | +2. **When conflicts occur**: The tool stops and lists conflicting files |
| 40 | +3. **Analyze conflicts**: Read the conflicting files, understand what's different between branches |
| 41 | +4. **Resolve conflicts**: Edit files to resolve, then `git add` the resolved files |
| 42 | +5. **Continue**: Run `backport --continue` to resume |
| 43 | +6. **Repeat** if more conflicts arise |
| 44 | +7. **Complete**: The backport tool pushes and creates the PR (do not use `gh` CLI to make the PR) |
| 45 | + |
| 46 | +## Conflict Resolution Guidelines |
| 47 | + |
| 48 | +**Simple conflicts you can resolve directly:** |
| 49 | +- Import statement conflicts |
| 50 | +- Simple variable name changes |
| 51 | +- Basic formatting differences |
| 52 | +- Minor API signature changes that are obvious |
| 53 | + |
| 54 | +**Complex conflicts - ask the user for guidance:** |
| 55 | +- Conflicts involving significant logic changes |
| 56 | +- Dependencies that don't exist in the target branch |
| 57 | +- API changes requiring substantial modification |
| 58 | +- Multiple conflicting files with interdependent changes |
| 59 | +- Changes that may not be appropriate for the target branch |
| 60 | + |
| 61 | +## When Resolving Conflicts |
| 62 | + |
| 63 | +1. **Explain what's conflicting** - show the relevant code sections |
| 64 | +2. **Explain why** - what's different between branches that caused this |
| 65 | +3. **Propose a resolution** - or ask for guidance if complex |
| 66 | +4. **After resolving**: `git add <files>` then `backport --continue` |
0 commit comments