ziggie
dbb3a9e953
-Due to a newer version we need to use add_labels instead of just labels -The backport PR will now also copy the milestones in case the milstones were set
527 lines
13 KiB
Markdown
527 lines
13 KiB
Markdown
# Automated Backport Workflow
|
|
|
|
This document describes the automated backport workflow for the LND project.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Overview](#overview)
|
|
2. [How to Use](#how-to-use)
|
|
3. [Workflow Triggers](#workflow-triggers)
|
|
4. [Label Format](#label-format)
|
|
5. [Workflow Steps](#workflow-steps)
|
|
6. [Handling Conflicts](#handling-conflicts)
|
|
7. [Multiple Backports](#multiple-backports)
|
|
8. [Technical Details](#technical-details)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
|
|
## Overview
|
|
|
|
The automated backport workflow simplifies the process of backporting merged PRs from the `master` branch to release branches (e.g., `v0.20.x-branch`, `v0.19.x-branch`).
|
|
|
|
Instead of manually creating branches, cherry-picking commits, and creating PRs, maintainers can simply add a label to the master PR, and the workflow handles the rest.
|
|
|
|
## How to Use
|
|
|
|
### Basic Usage
|
|
|
|
1. **Merge a PR to master** (or have it already merged)
|
|
2. **Add a backport label** in the format: `backport-v<version>-branch`
|
|
- Example: `backport-v0.20.x-branch`
|
|
3. **The workflow automatically**:
|
|
- Validates the target branch exists
|
|
- Cherry-picks the commits
|
|
- Creates a new PR targeting the release branch
|
|
- Adds the `no-changelog` label (since release notes are in the master PR)
|
|
|
|
### Example Scenario
|
|
|
|
```
|
|
Day 1, 10:00 - PR #1234 "Fix critical bug" merged to master
|
|
Day 1, 10:30 - Add label: backport-v0.20.x-branch
|
|
Day 1, 10:31 - Workflow creates PR #1235 automatically
|
|
Title: "[v0.20.x-branch] Backport #1234: Fix critical bug"
|
|
Base: v0.20.x-branch
|
|
Labels: no-changelog
|
|
Day 1, 14:00 - Maintainer reviews and merges PR #1235
|
|
```
|
|
|
|
## Workflow Triggers
|
|
|
|
The backport workflow triggers in two scenarios:
|
|
|
|
### Scenario 1: Label Before Merge
|
|
|
|
```
|
|
1. Open PR #1234
|
|
2. Add label: backport-v0.20.x-branch
|
|
3. Review and approve PR
|
|
4. Merge PR #1234
|
|
5. → Workflow triggers on PR close event
|
|
6. → Backport PR #1235 created immediately
|
|
```
|
|
|
|
### Scenario 2: Label After Merge
|
|
|
|
```
|
|
1. Open PR #1234
|
|
2. Review, approve, and merge PR #1234
|
|
3. Later... decide it needs backporting
|
|
4. Add label: backport-v0.20.x-branch
|
|
5. → Workflow triggers on label event
|
|
6. → Backport PR #1235 created immediately
|
|
```
|
|
|
|
Both scenarios work identically.
|
|
|
|
## Label Format
|
|
|
|
### Valid Labels
|
|
|
|
Labels **must** start with `backport-v` to trigger the workflow:
|
|
|
|
- ✅ `backport-v0.20.x-branch` → backports to `v0.20.x-branch`
|
|
- ✅ `backport-v0.19.x-branch` → backports to `v0.19.x-branch`
|
|
- ✅ `backport-v0.18.x-beta-branch` → backports to `v0.18.x-beta-branch`
|
|
|
|
### Invalid Labels (Will NOT Trigger)
|
|
|
|
These labels are ignored by the workflow:
|
|
|
|
- ❌ `backport candidate` - discussion label only
|
|
- ❌ `backport-candidate` - doesn't start with `backport-v`
|
|
- ❌ `backport-needed` - doesn't start with `backport-v`
|
|
- ❌ `needs-backport` - wrong prefix
|
|
|
|
This allows you to use discussion labels without accidentally triggering backports.
|
|
|
|
### Label to Branch Mapping
|
|
|
|
The label format directly maps to the target branch:
|
|
|
|
```
|
|
Label: backport-v0.20.x-branch
|
|
↓ (removes "backport-" prefix)
|
|
Branch: v0.20.x-branch
|
|
```
|
|
|
|
## Workflow Steps
|
|
|
|
The workflow executes the following steps when triggered:
|
|
|
|
### Step 1: Checkout Repository
|
|
|
|
```yaml
|
|
- Fetches the full git history
|
|
- Checks out the base branch (usually master)
|
|
```
|
|
|
|
### Step 2: Validate Target Branches
|
|
|
|
```bash
|
|
For each backport label:
|
|
1. Extract branch name from label
|
|
backport-v0.20.x-branch → v0.20.x-branch
|
|
|
|
2. Check if branch exists in remote repository
|
|
git ls-remote --heads origin v0.20.x-branch
|
|
|
|
3. If branch doesn't exist:
|
|
- Log error message
|
|
- Add branch to missing_branches list
|
|
|
|
4. After checking all labels:
|
|
- If any branches are missing → FAIL workflow
|
|
- If all branches exist → Continue
|
|
```
|
|
|
|
**Example validation output:**
|
|
|
|
```
|
|
All labels: ["backport-v0.20.x-branch", "bug-fix", "backport-v0.19.x-branch"]
|
|
Found backport labels:
|
|
backport-v0.20.x-branch
|
|
backport-v0.19.x-branch
|
|
|
|
Checking if branch exists: v0.20.x-branch
|
|
✓ Branch 'v0.20.x-branch' exists
|
|
|
|
Checking if branch exists: v0.19.x-branch
|
|
✓ Branch 'v0.19.x-branch' exists
|
|
|
|
✓ All target branches validated successfully
|
|
```
|
|
|
|
### Step 3: Create Backport PRs
|
|
|
|
For each valid backport label, the workflow:
|
|
|
|
1. **Creates a new branch**
|
|
- Branch name: `backport-<pr-number>-to-<target-branch>`
|
|
- Example: `backport-1234-to-v0.20.x-branch`
|
|
- Based on: the target release branch
|
|
|
|
2. **Cherry-picks commits**
|
|
- Uses `git cherry-pick` (not merge or rebase)
|
|
- Cherry-picks all commits from the original PR
|
|
- Preserves commit messages and authorship
|
|
- Skips merge commits
|
|
|
|
3. **Creates a new PR**
|
|
- Title: `[v0.20.x-branch] Backport #1234: <original-title>`
|
|
- Base branch: `v0.20.x-branch`
|
|
- Head branch: `backport-1234-to-v0.20.x-branch`
|
|
- Labels: `no-changelog` (automatically added)
|
|
|
|
4. **PR Description**
|
|
```markdown
|
|
Backport of #1234
|
|
|
|
Original PR: https://github.com/lightningnetwork/lnd/pull/1234
|
|
|
|
---
|
|
|
|
[Original PR description here]
|
|
```
|
|
|
|
## Handling Conflicts
|
|
|
|
The workflow handles merge conflicts gracefully using the `draft_commit_conflicts` strategy.
|
|
|
|
### When Cherry-pick Succeeds
|
|
|
|
```
|
|
1. Cherry-pick completes cleanly
|
|
2. Creates regular PR (ready for review)
|
|
3. PR is NOT in draft mode
|
|
4. Maintainer can review and merge immediately
|
|
```
|
|
|
|
### When Cherry-pick Has Conflicts
|
|
|
|
```
|
|
1. Cherry-pick encounters conflicts
|
|
2. Workflow commits the conflict markers:
|
|
<<<<<<< HEAD
|
|
[code from release branch]
|
|
=======
|
|
[code from master PR]
|
|
>>>>>>> commit-hash
|
|
|
|
3. Creates DRAFT PR
|
|
4. PR description indicates there were conflicts
|
|
5. Manual resolution required:
|
|
a. git fetch origin
|
|
b. git checkout backport-1234-to-v0.20.x-branch
|
|
c. Resolve conflicts in affected files
|
|
d. git add <resolved-files>
|
|
e. git commit -m "Resolve backport conflicts"
|
|
f. git push origin backport-1234-to-v0.20.x-branch
|
|
g. Mark PR as "Ready for review" in GitHub UI
|
|
6. Maintainer reviews and merges
|
|
```
|
|
|
|
### Conflict Resolution Best Practices
|
|
|
|
- **Review the original PR**: Understand what changed
|
|
- **Check the release branch**: Understand why conflicts occurred
|
|
- **Test after resolving**: Run tests locally before pushing
|
|
- **Update commit message**: Explain what conflicts were resolved and how
|
|
- **Request review**: Don't merge without review, even after resolving conflicts
|
|
|
|
## Multiple Backports
|
|
|
|
You can backport to multiple release branches simultaneously by adding multiple labels.
|
|
|
|
### Example: Backport to Two Branches
|
|
|
|
```
|
|
PR #1234 merged with labels:
|
|
- backport-v0.20.x-branch
|
|
- backport-v0.19.x-branch
|
|
|
|
Workflow creates TWO backport PRs:
|
|
|
|
PR #1235:
|
|
Title: [v0.20.x-branch] Backport #1234: Original title
|
|
Base: v0.20.x-branch
|
|
Labels: no-changelog
|
|
|
|
PR #1236:
|
|
Title: [v0.19.x-branch] Backport #1234: Original title
|
|
Base: v0.19.x-branch
|
|
Labels: no-changelog
|
|
```
|
|
|
|
### Independent Processing
|
|
|
|
Each backport is processed independently:
|
|
|
|
- One backport may succeed while another has conflicts
|
|
- One backport may fail validation while another succeeds
|
|
- Each backport creates a separate branch and PR
|
|
- Each backport PR is reviewed and merged independently
|
|
|
|
### Example with Mixed Results
|
|
|
|
```
|
|
PR #1234 with labels:
|
|
- backport-v0.20.x-branch → ✓ Clean cherry-pick, regular PR created
|
|
- backport-v0.19.x-branch → ✗ Conflicts, draft PR created
|
|
- backport-v0.99.x-branch → ✗ Branch doesn't exist, workflow fails
|
|
```
|
|
|
|
In this case:
|
|
1. PR #1235 to v0.20.x-branch is ready for review
|
|
2. PR #1236 to v0.19.x-branch needs conflict resolution
|
|
3. No PR created for v0.99.x-branch (validation failed)
|
|
4. Remove the incorrect label and add the correct one. The workflow will
|
|
re-trigger when you add the new label.
|
|
|
|
## Technical Details
|
|
|
|
### Workflow File
|
|
|
|
Location: `.github/workflows/backport.yml`
|
|
|
|
### Trigger Events
|
|
|
|
```yaml
|
|
on:
|
|
pull_request_target:
|
|
types: [closed, labeled]
|
|
```
|
|
|
|
- **closed**: Triggers when PR is closed (checks if merged)
|
|
- **labeled**: Triggers when any label is added
|
|
|
|
### Permissions Required
|
|
|
|
```yaml
|
|
permissions:
|
|
contents: write # Create branches and commits
|
|
pull-requests: write # Create and manage PRs
|
|
issues: read # Read PR metadata
|
|
```
|
|
|
|
### Workflow Condition
|
|
|
|
```yaml
|
|
if: |
|
|
github.event.pull_request.merged == true &&
|
|
contains(join(github.event.pull_request.labels.*.name, ','), 'backport-v')
|
|
```
|
|
|
|
Only runs when:
|
|
1. PR is actually merged (not just closed)
|
|
2. At least one label contains `backport-v`
|
|
|
|
### Label Pattern
|
|
|
|
```yaml
|
|
label_pattern: '^backport-(v.+)$'
|
|
```
|
|
|
|
Regex explanation:
|
|
- `^` - Start of string
|
|
- `backport-` - Literal text
|
|
- `(v.+)` - Capture group: "v" followed by one or more characters
|
|
- `$` - End of string
|
|
|
|
Examples:
|
|
- `backport-v0.20.x-branch` → matches, captures `v0.20.x-branch`
|
|
- `backport-v0.19.x-branch` → matches, captures `v0.19.x-branch`
|
|
- `backport-candidate` → doesn't match (no "v" after dash)
|
|
|
|
### Cherry-pick Strategy
|
|
|
|
```yaml
|
|
merge_commits: skip
|
|
```
|
|
|
|
- Uses `git cherry-pick` for clean history
|
|
- Skips merge commits (only cherry-picks actual changes)
|
|
- Preserves original commit messages and authorship
|
|
- Maintains PGP signatures where present
|
|
|
|
### Conflict Resolution Strategy
|
|
|
|
```yaml
|
|
experimental: |
|
|
conflict_resolution: draft_commit_conflicts
|
|
```
|
|
|
|
- Creates draft PR with conflict markers
|
|
- Allows manual resolution
|
|
- Preserves all context and metadata
|
|
|
|
## Troubleshooting
|
|
|
|
### Problem: Workflow Doesn't Trigger
|
|
|
|
**Symptoms:**
|
|
- Added `backport-v0.20.x-branch` label
|
|
- No workflow run appears in Actions tab
|
|
|
|
**Possible causes:**
|
|
|
|
1. **Label format is wrong**
|
|
- ❌ `backport-0.20.x-branch` (missing "v")
|
|
- ✅ `backport-v0.20.x-branch`
|
|
|
|
2. **PR is not merged**
|
|
- Workflow only runs on merged PRs
|
|
- Check PR status
|
|
|
|
3. **Workflow is disabled**
|
|
- Check `.github/workflows/backport.yml` exists
|
|
- Check workflow is enabled in Settings → Actions
|
|
|
|
### Problem: Workflow Fails with "Branch doesn't exist"
|
|
|
|
**Error message:**
|
|
```
|
|
Error: Target branch 'v0.21.x-branch' does not exist (from label 'backport-v0.21.x-branch')
|
|
Error: The following target branches do not exist: v0.21.x-branch
|
|
Error: Please ensure the branch exists before adding the backport label
|
|
```
|
|
|
|
**Solution:**
|
|
|
|
1. **Verify branch name:**
|
|
```bash
|
|
git ls-remote --heads origin | grep v0.21
|
|
```
|
|
|
|
2. **Check available release branches:**
|
|
```bash
|
|
git branch -r | grep origin/v0 | grep -v fork
|
|
```
|
|
|
|
3. **Fix the label:**
|
|
- Remove incorrect label
|
|
- Add correct label with existing branch name
|
|
|
|
### Problem: Cherry-pick Has Conflicts
|
|
|
|
**Symptoms:**
|
|
- Backport PR created as DRAFT
|
|
- PR description mentions conflicts
|
|
- Branch has files with conflict markers
|
|
|
|
**Solution:**
|
|
|
|
1. **Fetch and checkout the branch:**
|
|
```bash
|
|
git fetch origin
|
|
git checkout backport-1234-to-v0.20.x-branch
|
|
```
|
|
|
|
2. **Find conflicted files:**
|
|
```bash
|
|
grep -r "<<<<<<< HEAD" .
|
|
```
|
|
|
|
3. **Resolve each conflict:**
|
|
- Open the file in an editor
|
|
- Review both versions:
|
|
```
|
|
<<<<<<< HEAD
|
|
[Release branch version]
|
|
=======
|
|
[Master PR version]
|
|
>>>>>>> commit-hash
|
|
```
|
|
- Choose the correct code or merge both
|
|
- Remove conflict markers
|
|
|
|
4. **Commit the resolution:**
|
|
```bash
|
|
git add <resolved-files>
|
|
git commit -m "Resolve backport conflicts for PR #1234
|
|
|
|
Conflicts occurred due to [explanation].
|
|
Resolution: [describe what you did]"
|
|
git push origin backport-1234-to-v0.20.x-branch
|
|
```
|
|
|
|
5. **Mark PR ready for review:**
|
|
- Go to PR on GitHub
|
|
- Click "Ready for review"
|
|
|
|
### Problem: Multiple Labels but Only One Backport Created
|
|
|
|
**Symptoms:**
|
|
- Added `backport-v0.20.x-branch` and `backport-v0.19.x-branch`
|
|
- Only one PR created
|
|
|
|
**Possible causes:**
|
|
|
|
1. **One label format is wrong**
|
|
- Check both labels start with `backport-v`
|
|
- Fix incorrect label, workflow will retry
|
|
|
|
2. **One branch doesn't exist**
|
|
- Check workflow logs for validation errors
|
|
- Verify both branches exist
|
|
|
|
3. **Workflow still running**
|
|
- Check Actions tab for in-progress runs
|
|
- Wait for workflow to complete
|
|
|
|
### Problem: Backport PR Missing `no-changelog` Label
|
|
|
|
**Symptoms:**
|
|
- Backport PR created successfully
|
|
- CI fails on changelog check
|
|
|
|
**Solution:**
|
|
|
|
1. **Manually add the label:**
|
|
- Add `no-changelog` label to the backport PR
|
|
|
|
2. **Check workflow configuration:**
|
|
- Verify `.github/workflows/backport.yml` has:
|
|
```yaml
|
|
add_labels: no-changelog
|
|
```
|
|
|
|
3. **Re-run the workflow:**
|
|
- Remove and re-add the backport label on original PR
|
|
- New backport PR will have correct label
|
|
|
|
### Getting Help
|
|
|
|
If you encounter issues not covered here:
|
|
|
|
1. **Check workflow logs:**
|
|
- Go to Actions tab
|
|
- Click on the failed workflow run
|
|
- Review step-by-step logs
|
|
|
|
2. **Check workflow file:**
|
|
- `.github/workflows/backport.yml`
|
|
- Verify configuration matches this documentation
|
|
|
|
3. **Manual backport:**
|
|
- If automated backport fails repeatedly, you can backport manually:
|
|
```bash
|
|
# Create branch from target release branch
|
|
git checkout v0.20.x-branch
|
|
git checkout -b manual-backport-123-to-v0.20.x
|
|
|
|
# Cherry-pick commits from the original PR
|
|
git cherry-pick <commit-hash>
|
|
|
|
# Resolve any conflicts, then:
|
|
git add .
|
|
git commit
|
|
git push origin manual-backport-123-to-v0.20.x
|
|
|
|
# Create PR targeting v0.20.x-branch with no-changelog label
|
|
gh pr create --base v0.20.x-branch --label no-changelog
|
|
```
|
|
|
|
4. **Report issues:**
|
|
- If you find a bug in the workflow
|
|
- Open an issue with workflow logs and details
|