July 2026 Patches Merge-back

.github/skills/azsdk-common-patch-mergeback/SKILL.md

@@ -0,0 +1,100 @@
+---
+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.

.github/skills/azsdk-common-patch-mergeback/references/changelog-resolution.md

@@ -0,0 +1,70 @@
+# Reconciling `CHANGELOG.md` files
+
+Patches revert each library's `CHANGELOG.md` to its last stable release, dropping
+the `(Unreleased)` section and any newer entries that exist on `main`. The
+merge-back must restore `main`'s content **and** insert the patch entry.
+
+## Target structure of the resolved file
+
+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, 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.
+3. **The remainder of the file exactly as it is on `main`** (all previously
+   released entries, unchanged).
+
+Concretely: take the `main` version of the file and **insert the release
+branch's `PATCH_DATE` entry immediately below the `(Unreleased)` section.**
+Nothing else changes.
+
+## Rules
+
+- The patch entry's heading must carry `PATCH_DATE` (the `YYYY-MM-DD` derived
+  from the release branch name), not `(Unreleased)`.
+- Do not merge, reorder, or de-duplicate other entries.
+- Do not modify wording anywhere except inserting the patch block.
+- Verify dependency-bump bullets inside the patch entry reference the correct
+  "from" version (the previously released version). Correct them if the release
+  branch entry is wrong.
+
+## Example (before → after)
+
+`main` CHANGELOG top:
+```
+## 12.34.0-beta.1 (Unreleased)
+
+### Features Added
+
+## 12.33.2 (2026-02-15)
+...
+```
+
+`RELEASE_BRANCH` patch entry:
+```
+## 12.33.3 (2026-07-01)
+
+### Bugs Fixed
+- Fixed ...
+```
+
+Resolved file:
+```
+## 12.34.0-beta.1 (Unreleased)
+
+### Features Added
+
+## 12.33.3 (2026-07-01)
+
+### Bugs Fixed
+- Fixed ...
+
+## 12.33.2 (2026-02-15)
+...
+```
+
+Repeat for every `CHANGELOG.md` in the last-two-commits diff of the release
+branch.

.github/skills/azsdk-common-patch-mergeback/references/version-client-resolution.md

@@ -0,0 +1,44 @@
+# Reconciling `eng/versioning/version_client.txt`
+
+## File format
+
+Each SDK line is `<groupId>:<artifactId>;dependency-version;current-version`.
+Read the header of [eng/versioning/version_client.txt](../../../../eng/versioning/version_client.txt)
+for the authoritative explanation. Key points:
+
+- **`dependency-version`** — what libraries *outside* the release group use as a
+  Maven dependency. A patch release bumps this to the newly released stable
+  version.
+- **`current-version`** — the in-development version of the library on `main`.
+  This must **not** change during a merge-back.
+
+## 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
+   release branch shows (patches revert `current-version` to the stable value).
+3. Leave every other line exactly as it is on `main`.
+
+Resulting line = `groupId:artifactId;<release-branch 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.
+- 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`
+- **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
+`current-version` stays `12.34.0-beta.1` (from `main`).

eng/pipelines/templates/stages/archetype-java-release-patch.yml

@@ -54,6 +54,11 @@ stages:
             displayName: 'Download Signed Artifacts'
             artifact: packages-signed
 
+          # Setup Maven mirror settings and authenticate with Azure Artifacts
+          - template: /eng/pipelines/templates/steps/maven-authenticate.yml
+            parameters:
+              SourceDirectory: $(Pipeline.Workspace)/azure-sdk-for-java
+
           # gpg-sign and create the flattened directory for ESRP bulk publish
           # Note: The maven release requires the files to be local GPG signed
           # Dev feed publishes use the gpg-sign-and-deply to do it in one step

eng/pipelines/templates/stages/archetype-sdk-client-patch.yml

@@ -96,8 +96,13 @@ extends:
                 Paths: $(SparseCheckoutDirectories)
                 SkipCheckoutNone: true
 
+            - task: PipAuthenticate@1
+              displayName: 'Pip Authenticate to Azure Artifacts'
+              inputs:
+                artifactFeeds: 'public/azure-sdk-for-python'
+
             - script: |
-                python -m pip install markdown2 BeautifulSoup4
+                python -m pip install markdown2==2.4.6 BeautifulSoup4==4.11.1
               displayName: 'pip install markdown2 and BeautifulSoup4'
 
             # Authenticate with Azure Artifacts