Azsdk Common Patch Mergeback Agent Skill

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

• Confirm inputs — Establish RELEASE_BRANCH and PATCH_DATE (see table

above). Fetch the branch: git fetch origin RELEASE_BRANCH.

• Create the working branch from main:

git checkout main && git pull then

git checkout -b copilot/merge-back-release-patch-YYYYMMDD.

• 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).

• Reconcile version_client.txt — Follow

references/version-client-resolution.md.

• Reconcile each CHANGELOG.md — Follow

references/changelog-resolution.md.

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

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

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