backport-review

Files (1)

• SKILL.md

SKILL.md (first lines)

## User Input

```text
$ARGUMENTS
```

The arguments may contain:

- A **change request URL** (required). If not provided, ask for it before proceeding.
- An optional **branch specifier** — either a branch name (e.g. `stable/2025.2`) or a release codename (e.g. `Flamingo`). When provided, use that branch for the upstream patch comparison instead of the oldest branch.

Parse the arguments as follows:

1. Extract the URL (the token starting with `http`).
2. If any remaining token looks like a branch name (`stable/...`, `unmaintained/...`, `master`) or a single word that could be a codename, treat it as the branch specifier.
3. If a **codename** is given (not a branch path), resolve it to a branch name by fetching `https://raw.githubusercontent.com/openstack/releases/refs/heads/master/data/series_status.yaml` and finding the entry whose `name` field matches the codename (case-insensitive). The corresponding `release-id` field gives the YYYY.N version; map it to `stable/<release-id>` (or `unmaintained/<release-id>` if the series status is `unmaintained`). If the codename cannot be resolved, report it to the user and halt.
4. Store the resolved branch (if any) as **`requested_branch`**. When absent, default behaviour applies (oldest branch).

## Goal

Perform a structured backport review:

1. Validate that the change request description contains at least one OSPRH Jira ticket reference.
2. Validate that each commit has at least one `Upstream-<release>: <url>` line in the change request description.
3. For each commit, use its `Change-Id` to locate the equivalent patch on upstream Gerrit (`review.opendev.org`), select the oldest upstream branch that carries that Change-Id, fetch both patches as `.patch` files, and compare them.
4. Produce a concise, structured report.

---

## Step 1 — Set Up Working Directory and Fetch Change Request Data

### 1a. Prepare working directory

Parse the MR number from the URL (e.g. `42` from `.../merge_requests/42`) and set up a clean, MR-scoped working directory:

```bash
MR_ID=42   # parsed from the URL
WORKDIR=/tmp/backport-review/mr${MR_ID}
rm -rf "${WORKDIR}"
mkdir -p "${WORKDIR}"
```

All files for this review are written under `${WORKDIR}`. Never reuse files from a previous run.

### 1b. Download downstream patch

```bash
curl -sL "{change_request_url}.patch" -o "${WORKDIR}/downstream.patch"
```

### 1c. Extract fields from the downstream patch

```bash
# List commits (From headers) with line numbers
grep -n "^From " "${WORKDIR}/downstream.patch"

# Extract all Change-Id lines with line numbers
grep -n "^Change-Id:" "${WORKDIR}/downstream.patch"

# Extract all Upstream-* reference lines from commit messages
grep -n "^Upstream-" "${WORKDIR}/downstream.patch"

# Extract OSPRH/OSPCIX ticket references from commit messages
grep -oP '(OSPRH|OSPCIX)-[0-9]+' "${WORKDIR}/downstream.patch" | sort -u
```

### 1d. Extract upstream refs and OSPRH tickets from the MR description

**Do not use WebFetch for this** — it may summarize and drop refs. Use `curl | grep` instead:

```bash
# Fetch raw MR page and extract ALL Upstream-* reference lines
curl -sL "{change_request_url}" \
  | grep -oP '(?<![a-zA-Z])Upstream-[A-Za-z0-9._-]+:\s*https://[^\s<"&]+' \
  | sed 's/&amp;/\&/g' \
  | sort -u > "${WORKDIR}/mr_upstream_refs.txt"
cat "${WORKDIR}/mr_upstream_refs.txt"

# Extract OSPRH/OSPCIX tickets from the MR page
curl -sL "{change_request_url}" | grep -oP '(OSPRH|OSPCIX)-[0-9]+' | sort -u
```

The combined set of `Upstream-*` lines from the `.patch` file and from `${WORKDIR}/mr_upstream_refs.txt` forms the complete upstream refs list. Deduplicate by URL.

Build a per-commit record:

```
commit_N:
  subject: <first line of commit message>
  change_id: I<hex>
```

And a global upstream refs list:

```
upstream_refs:
  - release: master|<year.seq>|<codename>
    url: https://review.opendev.org/c/openstack/<project>/+/<number>
    gerrit_number: <numeric id>
```

---

## Step 2 — Validate Required Metadata

### 2a. OSPRH/OSPCIX ticket check

Verify that at least one `OSPRH-NNNNN` or `OSPCIX-NNNNN` pattern appears anywhere in the change request description or commit messages. If absent, mark as **FAIL**.

### 2b. Upstream reference coverage

For **each** commit in the change request, exactly one of the following must be true:

**Option A — Has upstream:** At least one URL from the complete upstream refs list corresponds to an upstream Gerrit patch with the **same Change-Id** as that commit.

To build the per-commit mapping:

1. For every URL in the complete upstream refs list, parse its Gerrit change number.
2. From the Gerrit API results in Step 3, look up that change number and read its `change_id` field.

From openstack-k8s-operators/devskills, MIT.

More from openstack-k8s-operators/devskills