azsdk-common-patch-mergeback

---
name: azsdk-common-patch-mergeback
license: MIT
metadata:
  version: "1.0.0"
  distribution: shared
description: 'Prepare a merge-back PR that brings patch-release version, CHANGELOG, and pom.xml updates from a `release/patch/YYYYMMDD` branch back into `main`. **WORKFLOW SKILL**. USE FOR: "merge-back PR", "merge back patches", "patch release merge-back", "bring patch releases into main", "reconcile release/patch branch with main". DO NOT USE FOR: triggering SDK releases, incrementing versions for a new patch, general SDK code generation. INVOKES: eng/versioning/update_versions.py.'
compatibility: "Requires a checked-out azure-sdk-for-java repo with git access to the release/patch branch and Python installed for eng/versioning/update_versions.py."
---

# Patch Release Merge-back

Prepare a PR that merges the version, CHANGELOG, and downstream `pom.xml`
updates produced by a patch release (on a `release/patch/YYYYMMDD` branch) back
into `main`. Patches revert `CHANGELOG.md` and version files to the last stable
release, so a naive merge creates many conflicts. This skill encodes how to
resolve each file type correctly.

## Triggers

WHEN: "merge-back PR", "merge back patches", "patch release merge-back", "bring patch releases into main", "reconcile the patch branch"
DO NOT USE FOR: triggering an SDK release, incrementing versions for a new patch cycle, code generation.

## Inputs (variables)

Two values drive the whole workflow. Both come from the **"Increment versions
for patch releases"** PR (opened by `azure-sdk-automation[bot]`) that targets the
patch branch:

| Variable         | How to determine it                                                              | Current value           |
| ---------------- | ------------------------------------------------------------------------------- | ----------------------- |
| `RELEASE_BRANCH` | The branch the "Increment versions" PR targets: `release/patch/YYYYMMDD`.        | `release/patch/20260701` |
| `PATCH_DATE`     | Derived from the branch name `YYYYMMDD` → `YYYY-MM-DD`. Used in CHANGELOG entries. | `2026-07-01`            |

If either value is ambiguous, ask the user to confirm before proceeding.

## Critical Rules (read first)

- **Only the last two commits** of `RELEASE_BRANCH` carry the updates to bring
  back. Diff against `RELEASE_BRANCH~2` to scope the change set.
- **Never edit `pom.xml` by hand.** It is regenerated by
  `eng/versioning/update_versions.py` **after** `version_client.txt` is correct.
- **Do not touch `README.md` files.** Run the version script with `--skip-readme`
  so READMEs are left unchanged (README updates are handled separately).
- **`version_client.txt`:** update only the `dependency-version` of SDK
  libraries that changed on the release branch; **always keep the
  `current-version` from `main`.** Never reset beta versions to `beta.1`.
- **`CHANGELOG.md`:** keep the `PATCH_DATE` entry from the release branch; every
  other line must match `main`. Do not invent or edit any other CHANGELOG
  content.
- Base the merge-back branch on **`main`**, not on the release branch.

## Workflow

1. **Confirm inputs** — Establish `RELEASE_BRANCH` and `PATCH_DATE` (see table
   above). Fetch the branch: `git fetch origin RELEASE_BRANCH`.
2. **Create the working branch from `main`:**
   `git checkout main && git pull` then
   `git checkout -b copilot/merge-back-release-patch-YYYYMMDD`.
3. **Scope the changes** — List files touched by the last two commits:
   `git diff --name-only origin/RELEASE_BRANCH~2 origin/RELEASE_BRANCH`.
   Expect three kinds: `eng/versioning/version_client.txt`, many `CHANGELOG.md`,
   and many `pom.xml` (+ possibly `README.md`).
4. **Reconcile `version_client.txt`** — Follow
   [references/version-client-resolution.md](references/version-client-resolution.md).
5. **Reconcile each `CHANGELOG.md`** — Follow
   [references/changelog-resolution.md](references/changelog-resolution.md).
6. **Regenerate `pom.xml`** — From the repo root run the version script with the
   `--skip-readme` (`--sr`) flag so `README.md` files are left untouched:
   ```bash
   python eng/versioning/update_versions.py --skip-readme
   ```
   Do not stage any manual `pom.xml` edits; only the generated output. Confirm no
   `README.md` files appear in the resulting diff.
7. **Review & sanity-check** — Verify no v2 (`*-v2`) or unrelated libraries were
   touched, no `current-version` values were altered, and no beta version was
   reset to `beta.1`.
8. **Commit and open the PR against `main`** — Title it like
   `<Month> <Year> Patches Merge-back`. Summarize: bumped dependency versions,
   inserted `PATCH_DATE` CHANGELOG entries, and auto-generated pom.xml updates
   (READMEs intentionally left unchanged via `--skip-readme`).

## Examples

- "Prepare the merge-back PR for `release/patch/20260701` into main."
- "Bring the July 2026 patch releases back into main."

## Troubleshooting

- **`current-version` mismatch after regeneration** (e.g. `2.59.0-beta.1` vs
  `2.59.0-beta.2`): you likely overwrote a `current-version`. Restore it from
  `main`; only `dependency-version` should change.
- **Unexpected pom.xml diffs:** re-run `update_versions.py` only after
  `version_client.txt` is fully correct; stray diffs usually mean the version
  file still has a wrong entry.
- **Accidental v2 library changes:** revert them — patch merge-backs only cover
  the patched GA/beta libraries listed in the release branch diff.
- **Wrong CHANGELOG "from" versions** in `## X.Y.Z (PATCH_DATE)` dependency
  bullets: correct them to match the actual previous release, per the release
  branch entry.