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.
5. Reconcile each CHANGELOG.md — Follow 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:

   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.