@@ -10,11 +10,10 @@ compatibility: "Requires a checked-out azure-sdk-for-java repo with git access t
 
 # 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.
+Patch releases automatically prepare a PR that brings the released dependency
+versions, exact patch CHANGELOG entries, and downstream `pom.xml` updates from a
+`release/patch/YYYYMMDD` branch back into `main`. Use this skill to understand,
+validate, or recover that merge-back when automation fails.
 
 ## Triggers
 
@@ -36,46 +35,49 @@ 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.
+- `patch-changelog.md` on the release branch is the authoritative list of
+  patched artifacts and exact CHANGELOG blocks to bring back.
 - **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`.
+- **`version_client.txt`:** promote the patch version recorded in the manifest
+  into `dependency-version`; **always keep the `current-version` from `main`.**
+  If `main` already has a newer dependency version, keep it. 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.
+- Never include `patch-changelog.md`, source resets, README changes, or any
+  release-branch-only files in the merge-back.
 
 ## 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
+   above). Fetch the branch and verify it contains `patch-changelog.md`.
+2. **Run the merge-back helper from a clean clone:**
+   `pwsh eng/scripts/Create-Patch-Mergeback.ps1 -ReleaseBranch RELEASE_REF`.
+   Prefer the immutable release commit SHA used by the build; a branch name is
+   supported for manual recovery.
+   The helper checks out `origin/main`, applies the manifest, regenerates POMs,
+   and rejects unsupported file changes.
+3. **Reconcile `version_client.txt` if recovery is required** — Follow
    [references/version-client-resolution.md](references/version-client-resolution.md).
-5. **Reconcile each `CHANGELOG.md`** — Follow
+4. **Reconcile each `CHANGELOG.md` if recovery is required** — Follow
    [references/changelog-resolution.md](references/changelog-resolution.md).
-6. **Regenerate `pom.xml`** — From the repo root run the version script with the
+5. **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
+6. **Review & sanity-check** — Verify the diff contains only
+   `eng/versioning/version_client.txt`, manifest-listed `CHANGELOG.md` files,
+   and generated `pom.xml` files. Confirm no current versions changed and no
+   dependency versions were downgraded.
+7. **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`).
 
@@ -11,9 +11,9 @@ Produce, from top to bottom:
 1. **The `## X.Y.Z (Unreleased)` section exactly as it is on `main`** — including
    any unreleased entries already present there. Do not add to, edit, or remove
    unreleased content.
-2. **The patch entry from `RELEASE_BRANCH`**, i.e. the `## X.Y.Z (PATCH_DATE)`
-   section (e.g. `## 12.33.3 (2026-07-01)`). This is the *only* content taken
-   from the release branch.
+2. **The exact patch entry from `patch-changelog.md`**, i.e. the
+   `## X.Y.Z (PATCH_DATE)` section (e.g. `## 12.33.3 (2026-07-01)`). This is the
+   only release-branch content inserted into the target changelog.
 3. **The remainder of the file exactly as it is on `main`** (all previously
    released entries, unchanged).
 
 
@@ -12,32 +12,53 @@ for the authoritative explanation. Key points:
 - **`current-version`** — the in-development version of the library on `main`.
   This must **not** change during a merge-back.
 
+Patch changelog and merge-back scripts parse this file through
+`eng/scripts/Convert-VersionClientToJson.ps1`. The generated JSON is temporary
+and must not be committed. It is keyed by artifact coordinate:
+
+```json
+{
+  "com.azure:azure-example": {
+    "dependency": "1.0.0",
+    "current": "1.1.0-beta.1"
+  }
+}
+```
+
+Two-column external and unreleased entries have a `null` `current` value.
+`version_client.txt` remains the canonical file and the merge-back writes its
+updated dependency versions back to that file.
+
 ## Resolution algorithm
 
 Compare the file on `main` against the file on `RELEASE_BRANCH`, line by line
 (match by `groupId:artifactId`):
 
-1. If the release branch line has a **different `dependency-version`** than
-   `main`, take the release branch `dependency-version`.
-2. **Always keep the `current-version` from `main`**, regardless of what the
+1. Read the released patch version from the artifact's entry in
+   `patch-changelog.md`. During preparation this is also the release branch's
+   `current-version`.
+2. If that patch version is newer than `main`'s **`dependency-version`**, use
+   the patch version. If `main` already has an equal or newer dependency
+   version, keep the value from `main`.
+3. **Always keep the `current-version` from `main`**, regardless of what the
    release branch shows (patches revert `current-version` to the stable value).
-3. Leave every other line exactly as it is on `main`.
+4. Leave every other line exactly as it is on `main`.
 
-Resulting line = `groupId:artifactId;<release-branch dependency-version>;<main current-version>`.
+Resulting line = `groupId:artifactId;<newer of patch version or main dependency-version>;<main current-version>`.
 
 ## Guardrails
 
 - **Do not reset beta versions to `beta.1`.** If a `current-version` on `main`
   is e.g. `1.2.0-beta.4`, it stays `1.2.0-beta.4`.
-- Only touch SDK library lines whose `dependency-version` actually changed on
-  the release branch. Do not modify parent/BOM lines or unrelated libraries.
+- Only touch SDK library lines listed in `patch-changelog.md`. Do not modify
+  parent/BOM lines or unrelated libraries.
 - Never alter `current-version` values — a changed `current-version` is the most
   common merge-back bug and surfaces later as a pom.xml mismatch.
 
 ## Example
 
 - `main`:           `com.azure:azure-storage-blob;12.33.2;12.34.0-beta.1`
-- `RELEASE_BRANCH`: `com.azure:azure-storage-blob;12.33.3;12.33.3`
+- `RELEASE_BRANCH`: `com.azure:azure-storage-blob;12.33.2;12.33.3`
 - **Result:**       `com.azure:azure-storage-blob;12.33.3;12.34.0-beta.1`
 
 Here the dependency-version moves `12.33.2` → `12.33.3` (the patch), while the
 
@@ -1,10 +1,10 @@
-# Path Release Pipeline
+# Patch Release Pipeline
 
 The patch release pipeline is a pipeline designed to release a patch of updated azure-sdk-for-java Artifacts in preparation for release of the Azure Java SDK BOM (Bill of Materials).
 
 ## Prerequisites
 
-The patch release pipeline differs from service directory pipelines in that the Artifacts list should change, every time, prior to this pipeline being run. The list of what Artifacts and external dependencies that needs updated, built, and released, to enable the BOM release, is computed by other Java scripts. The last part of this computation feeds in the computed artifacts list to the [Update-Artifacts-List-For-Patch-Release.ps1][update_for_release_script] script which, in turn, updates the [patch-release.yml][patch_release_yml] file's Artifacts and AdditionalModules lists. The updated patch-release.yml should be checked in along with the version_client.txt, pom, CHANGELOG and README updates when prepping for the patch release.
+The patch release pipeline differs from service directory pipelines in that the Artifacts list should change, every time, prior to this pipeline being run. The list of what Artifacts and external dependencies that needs updated, built, and released, to enable the BOM release, is computed by other Java scripts. The last part of this computation feeds in the computed artifacts list to the [Update-Artifacts-List-For-Patch-Release.ps1][update_for_release_script] script which, in turn, updates the [patch-release.yml][patch_release_yml] file's Artifacts and AdditionalModules lists. The prepare pipeline also removes entries from `external_dependencies.txt` that are not referenced by version-update markers in any POM file. The updated patch-release.yml should be checked in along with the version_client.txt, external_dependencies.txt, pom, CHANGELOG, README, and generated `patch-changelog.md` updates when prepping for the patch release.
 
 ### [Update-Artifacts-List-For-Patch-Release.ps1][update_for_release_script]
 
@@ -26,6 +26,30 @@ This is the yml file that belongs to the [java - patch-release][java_patch_relea
 
 The [java - patch-release][java_patch_release] pipeline is manual only. There is no purpose to running this pipeline other than than to release a patch build. The pipeline will build, analyze, verify and release the set of Artifacts that are in the patch-release.yml.
 
+After package publication succeeds, the pipeline creates a merge-back PR against
+`main`. It does not merge the patch release branch. The PR contains only:
+
+- released dependency versions promoted into `eng/versioning/version_client.txt`,
+  while keeping `main`'s current versions;
+- the exact patch entries recorded in `patch-changelog.md`; and
+- `pom.xml` updates generated by
+  `python eng/versioning/update_versions.py --skip-readme`.
+
+If `main` already contains a newer dependency version, the merge-back keeps the
+newer value. Source resets, README changes, `patch-changelog.md`, and all other
+patch-branch changes are intentionally excluded.
+
+### `patch-changelog.md`
+
+The prepare pipeline generates `patch-changelog.md` at the repository root after
+all patch artifacts have been prepared. Each entry records the artifact
+coordinate, repository-relative changelog path, released patch version, and the
+exact markdown block generated for that release.
+
+The file is committed to the patch release branch so the release pipeline can
+consume deterministic changelog content. It is a transient release artifact and
+must not be copied or merged into `main`.
+
 ### How build works in the patch build pipeline
 
 Normal service directory pipelines are only concerned with the set of Artifacts that live within that service directory. Any interdependencies within that service directory use current versions of each other and any dependencies outside of that service directory use the dependency versions. When a artifacts from a service directory are released, the released version becomes the new dependency version and everything that depends on it gets the updated version. This is why monthly releases have a release order. The From Source runs, which are part of every test matrix, is how we know this process works.
@@ -36,12 +60,15 @@ The patch-release pipeline utilizes the same tools that the From Source runs use
 
 **Release verifications are done in the AnalyzeAndVerify Job.** In the patch-release pipeline, verifications normally done as part of the release task in service directories pipelines are now being done as part of the AnalyzeAndVerify job. This can be done since there's no ambiguity as to whether or not the artifacts are going to be released.
 
-**Testing is not done in the patch-release pipeline.** Unlike service directory pipelines, there are no tests being run. We have a highly customizable test matrix which many service directories have made changes to. Because of this, it's nearly impossible to rectify a test matrix for a set of artifacts that spans the entire repository. There is a mitigation for this; as part of the preparation for patch release versions, poms, CHANGELOG and README files all need to be updated. These updates will cause each individual service directory pipeline to get run as part of the process for the update PR. In between the update PR and kicking off the patch-release pipeline, there should be no outside changes that aren't related to the aforementioned update. The matrix of FromSource and non-FromSource runs should provide enough verification. We already make the same assumptions when we release service directory, update the dependency version and then release a service directory that depends on what was previously released.
+**Testing is not done in the patch-release pipeline.** Unlike service directory pipelines, there are no tests being run. We have a highly customizable test matrix which many service directories have made changes to. Because of this, it's nearly impossible to rectify a test matrix for a set of artifacts that spans the entire repository. There is a mitigation for this; as part of the preparation for patch release versions, POM, CHANGELOG, README, and patch changelog manifest files all need to be updated. These updates will cause each individual service directory pipeline to get run as part of the process for the update PR. In between the update PR and kicking off the patch-release pipeline, there should be no outside changes that aren't related to the aforementioned update. The matrix of FromSource and non-FromSource runs should provide enough verification. We already make the same assumptions when we release service directory, update the dependency version and then release a service directory that depends on what was previously released.
 
 ## Testing changes/updates to the patch-release pipeline
 
-The easiest way to test the patch release pipeline is to use the example above which sets the Artifacts list to the
-list of template libraries. After running, add the following parameter **TestPipeline**: **true**. This will allow the release of the template libraries without any version preparation, just run and release. The parameter will cause the test pipeline version code, which sets template libraries to a new beta version, based upon the buildId, for release and then auto closes the version increment PR.
+The merge-back path requires a prepared patch branch containing
+`patch-changelog.md`. Run the prepare pipeline with the intended test artifact
+set, then run the patch release pipeline from that branch with
+**TestPipeline** set to **true**. The test parameter keeps the existing
+test-package behavior and automatically closes the generated merge-back PR.
 
 <!-- LINKS -->
 [java_patch_release]: https://dev.azure.com/azure-sdk/internal/_build?definitionId=5015&_a=summary
 
@@ -19,6 +19,7 @@ extends:
       - stage: PreparePatchRelease
         displayName: Prepare Patch Release
         variables:
+          - template: /eng/pipelines/templates/variables/globals.yml
           - template: /eng/pipelines/templates/variables/image.yml
         jobs:
           - job: PreparePatchRelease
@@ -68,6 +69,23 @@ extends:
                 env:
                   SYSTEM_ACCESSTOKEN: $(System.AccessToken)
 
+              - task: UsePythonVersion@0
+                displayName: 'Use Python $(PythonVersion)'
+                inputs:
+                  versionSpec: $(PythonVersion)
+
+              - task: PythonScript@0
+                displayName: 'Remove unused external dependencies'
+                inputs:
+                  scriptPath: eng/versioning/find_unused_dependencies.py
+                  arguments: --remove-unused-external-dependencies
+
+              - task: PowerShell@2
+                displayName: 'Generate patch changelog manifest'
+                inputs:
+                  pwsh: true
+                  filePath: eng/scripts/New-PatchChangelog.ps1
+
               # Create a PR with the patches prepared
               - template: /eng/common/pipelines/templates/steps/create-pull-request.yml
                 parameters:
 
@@ -11,6 +11,7 @@ extends:
   template: /eng/pipelines/templates/stages/archetype-sdk-client-patch.yml
   parameters:
     TestPipeline: ${{ parameters.TestPipeline }}
+    PatchMergeBack: true
     artifacts:
     - name: azure-sdk-template
       groupId: com.azure
@@ -42,4 +43,3 @@ extends:
       safeName: azuresdktemplatethree
       skipPublishDocMs: true
       ServiceDirectory: template-v2
-