azsdk-common-patch-mergeback

# 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.