Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions .github/skills/azsdk-java-patch-mergeback/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 32 additions & 5 deletions eng/pipelines/Patch-Release-README.md
Original file line number Diff line number Diff line change
@@ -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]

Expand All @@ -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.
Expand All @@ -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
Expand Down
18 changes: 18 additions & 0 deletions eng/pipelines/patch-release-prepare.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion eng/pipelines/patch-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -42,4 +43,3 @@ extends:
safeName: azuresdktemplatethree
skipPublishDocMs: true
ServiceDirectory: template-v2

Loading
Loading