rhdh-backport

Files (13)

• README.md
• SKILL.md
• openai.yaml · agents/
• ai-conflict-resolution.md · references/
• ci-monitoring.md · references/
• overlays-lookup.md · references/
• overlays-update.md · references/
• plugin-detection.md · references/
• pr-creation.md · references/
• pr-detection.md · references/
• version-packages-detection.md · references/
• workflow-bootstrap.md · references/
• backport.py · scripts/

SKILL.md (first lines)

<essential_principles>

<principle name="script_driven">
The script performs local preparation and read-only discovery. For every external
write it emits a WRITE_PLAN file and waits on stdin. The agent's role is:
1. Validate prerequisites, then invoke /mutation-gate for every WRITE_PLAN
2. Run the credential scanner on the plan, render its exact target, command,
   preview, precondition, failure behavior, and recovery as a conversation table
3. Only after the user approves that specific plan, send the printed
   WRITE_APPROVAL line to the still-running script via stdin
4. If approval is denied, send a line other than WRITE_APPROVAL so the
   process exits; report that write and later writes as skipped. If the
   precondition changed, prepare a new plan
5. Handle cherry-pick conflicts if the script exits with code 2
6. Report each write receipt, including failures and skipped operations
</principle>

<principle name="ai_conflict_resolution">
When the script exits with code 2 (cherry-pick conflict), it saves state to a JSON file
and prints the path as `STATE_FILE=<path>` to stderr. The agent must:

1. Read the state file to get the list of conflicting files
2. Present the user with TWO options:
   - Option 1: Let the skill resolve conflicts (AI auto-resolution)
   - Option 2: User resolves manually (abort)

If user chooses Option 1:
- Read each conflicting file (with conflict markers)
- Understand both sides of the conflict using `git log` and `git show`
- Generate intelligent resolution
- Write resolved files using Edit tool
- Validate syntax (npx tsc --noEmit for TypeScript)
- Check no conflict markers remain
- Run: `git add . && git cherry-pick --continue`
- Re-run script with `--continue-from <state_file>`

If user chooses Option 2:
- Print manual resolution instructions and stop

See `references/ai-conflict-resolution.md` for detailed resolution strategies.
</principle>

</essential_principles>

## Prerequisites

- **`gh` CLI** — installed and authenticated
- **Git access** — to `rhdh-plugins`
- **Fork** — of `rhdh-plugins` with `origin` remote pointing to fork
- **`upstream` remote** — pointing to `redhat-developer/rhdh-plugins`
- **Python 3.9+** — for the backport script

---

## Usage

```bash
/backport <release-version> <pr-source> [--mode auto|create|finish]
```

**Examples:**
```bash
# Full automation (default)
/backport 1.10 3456
/backport 2.1 3456
/backport 1.9 https://github.com/redhat-developer/rhdh-plugins/pull/2345

# Create PR only, stop for manual review
/backport 1.10 3456 --mode create

# Complete after manual PR merge
/backport 1.10 3456 --mode finish
```

---

## Modes

### auto (default) — Full workflow

Runs all 11 steps, pausing before each external write for the approval above.
Later PR numbers and workflow results are discovered at runtime, so approval for
the first push cannot approve the later merges or /publish comment. Keep stdin
attached in an interactive terminal; never pipe an automatic approval string.

```bash
python scripts/backport.py <release> <pr_source> --mode auto
```

### create — PR only, stops for review

Runs steps 1-7: workflow bootstrap, cherry-pick, push, create PR. Stops and prints the PR URL.
You review and merge manually, then run with `--mode finish`.

```bash
python scripts/backport.py <release> <pr_source> --mode create
```

### finish — After manual merge

Runs steps 8-11: Version Packages, overlays update, changelog.
Assumes PR #1 from `--mode create` is already merged.

```bash
python scripts/backport.py <release> <pr_source> --mode finish
```

---

## Branch strategies

The skill picks the branch model from the release version. **2.1 is the cutoff.**

### Unified release branch — 2.1+ (e.g. `release-2.1`)

- One branch per release, all workspaces (similar to `main`).
- Open patch PRs targeting `release-2.1` directly.
- Version Packages, overlays, and changelog steps are the same as pre-2.1.
- Version Packages PR comes from `maintenance-changesets-release/release-x.y/{plugin}`

From redhat-developer/rhdh-skills, Apache-2.0.

More from redhat-developer/rhdh-skills