Qv SDK Backmerge

SDK Pod Backmerge PR Creation

Create the backmerge PR that keeps main aligned with what shipped on a release-<pkg>-<x.y.z> branch, per docs/gitflow.md "Keep main aligned" sections.

When to use this skill

Applies to SDK pod packages whose paths are owned by .github/teams/sdk.json.

Use when:

• A release PR has been (or is being) created for release-<pkg>-<x.y.z>
• User invokes /qv-sdk-backmerge
• sdk-pr-create chains into this flow automatically when the target is a release branch (see that skill's "Release Target Dual-PR Flow")

The backmerge PR carries the version bump + changelog metadata from the release branch onto main so future development sees it. It is tagged [skiplog] to keep it out of subsequent changelogs.

@qvac/inference and @qvac/sdk release separately, so a new major.minor produces two release branches and two backmerges: release-inference-<x.y.z> (engine version + changelog) and then release-sdk-<x.y.z> (SDK version + its @qvac/inference range + changelog + docs). Run this skill once per release branch.

Inputs (resolve in priority order)

1. Active release-PR context (when chained from sdk-pr-create): release PR number/URL, release branch, source head branch, ticket
2. Explicit args when invoked standalone:
   • Release PR URL/number, OR
   • --package=<pkg> --version=<x.y.z> and one of --source=<head-branch> or --commit=<sha>
3. Inferred from current branch when no args given: if currently on a head branch that targets release-<pkg>-<x.y.z>, derive package, version, and source from it
4. ASK only if still ambiguous after the steps above

Branch / remote preference

Same policy as qv-sdk-pr-create: prefer pushing the backmerge head to the org remote (tetherto/qvac) and opening a same-repo PR. Personal-fork heads are a fallback and count as external for CI (fork-ci environment approval required per run on the current head SHA).

In command examples below, ORG_REMOTE / FORK_REMOTE are placeholders — substitute the resolved remote names from Step 1. Do not run those tokens literally.

Workflow

Step 1: Pre-flight

• gh is installed and authenticated (gh auth status)
• Working tree is clean (git status empty); if not, ASK whether to stash
• Identify org remote: scan git remote -v for the canonical org repo (tetherto/qvac.git); fall back to a remote literally named upstream. ASK if neither found.
• Identify fork remote if present (often origin when org is upstream) — used only when org push is unavailable or the user explicitly chooses the fork path
• Prefer org-branch push for the backmerge head

Step 2: Resolve the cherry-pick source

Sanity check: the source range must reflect release metadata only (version bump, changelog files, NOTICE, optional model registry/history, and for --package=sdk the two generated reference pages under docs/website/content/docs/sdk/). If git diff <range> --stat shows broad unrelated changes (suggesting the branch was based off main, not the release branch), STOP and ASK how to proceed — do not silently cherry-pick unrelated work onto main.

Step 3: Detect no-op (main already aligned)

Before creating the backmerge branch, check whether main already contains the release content.

git fetch ORG_REMOTE main
git fetch ORG_REMOTE release-<pkg>-<x.y.z>
git merge-tree --write-tree --merge-base=<src>^ ORG_REMOTE/main <src>
git rev-parse ORG_REMOTE/main^{tree}

The first command prints the tree SHA produced by simulating the cherry-pick. The second prints main's current tree SHA. If they are identical, every change in the source range is already on main:

1. STOP. Do not create a branch, do not push, do not open a PR.
2. Find the commit that landed the release content directly on main so you can cite it:

   git log ORG_REMOTE/main --oneline -1 -- <pkg-dir>/changelog/<x.y.z>/

   Resolve <pkg-dir> via node -p "require('./scripts/sdk/package-paths.cjs').getPackageDir('<pkg>')" (plugins use plugins/…, not packages/…).
3. Report to the user, e.g.:

   No backmerge PR needed — main is already aligned with release-<pkg>-<x.y.z>.
   The release content landed on main via <commit-sha> (<commit-subject>).

This avoids pushing an empty branch and a gh pr create failure.

Step 4: Sync and create the backmerge branch

git fetch ORG_REMOTE main
git fetch ORG_REMOTE release-<pkg>-<x.y.z>
git checkout -b backmerge/release-<pkg>-<x.y.z> ORG_REMOTE/main

If a local branch with that name already exists, ASK before overwriting.

Step 5: Cherry-pick

git cherry-pick -x <commit_or_range>

For a true merge commit (not squashed), add -m 1.