From 18a41e55af250089c34ea2c24843b522faa6d565 Mon Sep 17 00:00:00 2001 From: tsk Date: Mon, 27 Oct 2025 18:59:46 -0400 Subject: [PATCH] feat: backport bot (#1215) --- .backportrc.json | 7 ++ .github/templates/failed-backport-issue.md | 8 +++ .github/workflows/backport.yml | 68 +++++++++++++++++++ DEVELOPMENT.md | 79 ++++++++++++++++++++++ 4 files changed, 162 insertions(+) create mode 100644 .backportrc.json create mode 100644 .github/templates/failed-backport-issue.md create mode 100644 .github/workflows/backport.yml diff --git a/.backportrc.json b/.backportrc.json new file mode 100644 index 00000000..7978aa60 --- /dev/null +++ b/.backportrc.json @@ -0,0 +1,7 @@ +{ + "repoOwner": "cashubtc", + "repoName": "cdk", + "targetBranchChoices": ["v0.10.x", "v0.11.x", "v0.12.x", "v0.13.x"], + "autoMerge": false, + "autoMergeMethod": "merge" +} diff --git a/.github/templates/failed-backport-issue.md b/.github/templates/failed-backport-issue.md new file mode 100644 index 00000000..9e0b9c7a --- /dev/null +++ b/.github/templates/failed-backport-issue.md @@ -0,0 +1,8 @@ +--- +title: Backport PR `#{{ env.PR_NUMBER }}` {{ env.SHORT_PR_TITLE }} +labels: backport +--- +PR: #{{ env.PR_NUMBER }} +Title: {{ env.PR_TITLE }} + +The backport bot failed. Please open a PR to backport these changes. diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 00000000..4ef28a00 --- /dev/null +++ b/.github/workflows/backport.yml @@ -0,0 +1,68 @@ +name: Backport merged pull request +on: + pull_request_target: + # Run on merge (close) or if label is added after merging + types: [closed, labeled] + +# Set concurrency limit to a single backport workflow per branch +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + backport: + permissions: + contents: write # so it can comment + pull-requests: write # so it can create pull requests + name: Backport pull request + runs-on: ubuntu-latest + + # Don't run on closed unmerged pull requests or if a non-backport label is added + if: | + github.event.pull_request.merged && + ( + github.event.action != 'labeled' || + contains(github.event.label.name, 'backport') + ) + + outputs: + was_successful: ${{ steps.create-pr.outputs.was_successful }} + + steps: + - uses: actions/checkout@v4 + - id: create-pr + name: Create backport pull requests + uses: korthout/backport-action@v3 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + + open-issue: + permissions: + contents: read + issues: write + name: Open issue for failed backports + runs-on: ubuntu-latest + needs: backport + + # Open an issue only if the backport job failed + if: ${{ needs.backport.outputs.was_successful == 'false' }} + + steps: + - uses: actions/checkout@v4 + - name: Set SHORT_PR_TITLE env + run: | + SHORT_PR_TITLE=$( + echo '${{ github.event.pull_request.title }}' \ + | awk '{print (length($0) > 40) ? substr($0, 1, 40) "..." : $0}' + ) + echo "SHORT_PR_TITLE=$SHORT_PR_TITLE" >> "$GITHUB_ENV" + + - name: Create issue + uses: JasonEtco/create-an-issue@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.number }} + PR_TITLE: ${{ github.event.pull_request.title }} + SHORT_PR_TITLE: ${{ env.SHORT_PR_TITLE }} + with: + filename: .github/templates/failed-backport-issue.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 3ba67cd2..61db2d35 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -226,6 +226,85 @@ just final-check 4. Submit a pull request 5. Wait for review and address feedback +## Backporting Changes + +CDK uses an automated backport bot to help maintain stable release branches. This section explains how the backport process works. + +### How the Backport Bot Works + +The backport bot creates pull requests to backport merged changes from `main` to stable release branches. **You control which branches to backport to by adding labels to your PR.** + +**Available Target Branches:** +- `v0.10.x` +- `v0.11.x` +- `v0.12.x` +- `v0.13.x` + +### Using Backport Labels + +To backport a PR to specific stable branches, add labels to your PR **before or after merging**: + +**Label Format:** +- `backport v0.13.x` - backports to v0.13.x branch +- `backport v0.12.x` - backports to v0.12.x branch +- Add multiple labels to backport to multiple branches + +**Example Workflow:** +1. Create and merge your PR to `main` +2. Add label `backport v0.13.x` to the PR +3. The bot automatically creates a backport PR for the v0.13.x branch +4. Review and merge the backport PR +5. Repeat for other branches as needed + +**When to Add Labels:** +- Add labels before merging - backport PRs are created automatically on merge +- Add labels after merging - backport PRs are created when you add the label +- You can add multiple backport labels at once + +### When Backports Fail + +Sometimes the backport bot cannot automatically create a backport PR due to merge conflicts or other issues. When this happens: + +1. The bot automatically creates a GitHub issue labeled with `backport` +2. The issue will contain details about the original PR and which branch(es) failed +3. You'll need to manually create the backport PR for the failed branch + +**Manual Backporting Process:** +```bash +# Checkout the target stable branch +git checkout v0.13.x +git pull origin v0.13.x + +# Create a new branch for the backport +git checkout -b backport-pr-NUMBER-to-v0.13.x + +# Cherry-pick the commits from the original PR +git cherry-pick COMMIT_HASH + +# Resolve any conflicts if they occur +# Then push and create a PR +git push origin backport-pr-NUMBER-to-v0.13.x +``` + +### Best Practices for Backporting + +1. **Label Appropriately:** Only add backport labels for changes that should be in stable branches +2. **Keep PRs Focused:** Smaller, focused PRs are easier to backport automatically +3. **Review Backport PRs:** Always review automatically created backport PRs to ensure they're appropriate +4. **Test Backports:** Run tests on backport PRs just like regular PRs +5. **Address Conflicts Promptly:** If a backport fails, address it promptly or close the issue with an explanation + +### When NOT to Backport + +Not all changes should be backported to stable branches. **Don't add backport labels** for: +- Breaking API changes +- New features that aren't needed in older versions +- Changes that don't apply to older version branches +- Large refactorings +- Experimental or unstable features + +If a backport isn't appropriate, simply don't add the backport label to the PR. + ## Additional Resources - [Nix Documentation](https://nixos.org/manual/nix/stable/)