From 915c5300d0958f108dcd4e664b5c3f374a340e34 Mon Sep 17 00:00:00 2001 From: Jair Myree Date: Thu, 10 Sep 2026 15:39:09 -0400 Subject: [PATCH 1/5] Update patch release merge-back automation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../azsdk-java-patch-mergeback/SKILL.md | 52 +-- .../references/changelog-resolution.md | 6 +- .../references/version-client-resolution.md | 20 +- eng/pipelines/Patch-Release-README.md | 37 +- eng/pipelines/patch-release-prepare.yml | 9 + eng/pipelines/patch-release.yml | 3 +- .../stages/archetype-java-release-patch.yml | 74 +++- .../stages/archetype-sdk-client-patch.yml | 37 +- eng/scripts/Create-Patch-Mergeback.ps1 | 399 ++++++------------ eng/scripts/New-PatchChangelog.ps1 | 79 ++++ eng/scripts/patch-mergeback-helpers.ps1 | 331 +++++++++++++++ .../tests/Create-Patch-Mergeback.tests.ps1 | 105 +++++ .../tests/patch-mergeback-helpers.tests.ps1 | 178 ++++++++ 13 files changed, 987 insertions(+), 343 deletions(-) create mode 100644 eng/scripts/New-PatchChangelog.ps1 create mode 100644 eng/scripts/patch-mergeback-helpers.ps1 create mode 100644 eng/scripts/tests/Create-Patch-Mergeback.tests.ps1 create mode 100644 eng/scripts/tests/patch-mergeback-helpers.tests.ps1 diff --git a/.github/skills/azsdk-java-patch-mergeback/SKILL.md b/.github/skills/azsdk-java-patch-mergeback/SKILL.md index 079f5fd062549..3f1b4fdbc3117 100644 --- a/.github/skills/azsdk-java-patch-mergeback/SKILL.md +++ b/.github/skills/azsdk-java-patch-mergeback/SKILL.md @@ -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 ` 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`). diff --git a/.github/skills/azsdk-java-patch-mergeback/references/changelog-resolution.md b/.github/skills/azsdk-java-patch-mergeback/references/changelog-resolution.md index 706cb64669ddf..edaf2f14cfe42 100644 --- a/.github/skills/azsdk-java-patch-mergeback/references/changelog-resolution.md +++ b/.github/skills/azsdk-java-patch-mergeback/references/changelog-resolution.md @@ -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). diff --git a/.github/skills/azsdk-java-patch-mergeback/references/version-client-resolution.md b/.github/skills/azsdk-java-patch-mergeback/references/version-client-resolution.md index 7b3d58f2de5b5..c98b47be81b08 100644 --- a/.github/skills/azsdk-java-patch-mergeback/references/version-client-resolution.md +++ b/.github/skills/azsdk-java-patch-mergeback/references/version-client-resolution.md @@ -17,27 +17,31 @@ for the authoritative explanation. Key points: 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;;
`. +Resulting line = `groupId:artifactId;;
`. ## 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 diff --git a/eng/pipelines/Patch-Release-README.md b/eng/pipelines/Patch-Release-README.md index dc65039436911..d7b06a36645ca 100644 --- a/eng/pipelines/Patch-Release-README.md +++ b/eng/pipelines/Patch-Release-README.md @@ -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 updated patch-release.yml should be checked in along with the version_client.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. [java_patch_release]: https://dev.azure.com/azure-sdk/internal/_build?definitionId=5015&_a=summary diff --git a/eng/pipelines/patch-release-prepare.yml b/eng/pipelines/patch-release-prepare.yml index 0e29350ce66fc..ab2c798e0336b 100644 --- a/eng/pipelines/patch-release-prepare.yml +++ b/eng/pipelines/patch-release-prepare.yml @@ -68,6 +68,15 @@ extends: env: SYSTEM_ACCESSTOKEN: $(System.AccessToken) + - task: PowerShell@2 + displayName: 'Generate patch changelog manifest' + inputs: + pwsh: true + filePath: eng/scripts/New-PatchChangelog.ps1 + arguments: > + -PackagesYmlPath eng/pipelines/patch-release.yml + -OutputPath patch-changelog.md + # Create a PR with the patches prepared - template: /eng/common/pipelines/templates/steps/create-pull-request.yml parameters: diff --git a/eng/pipelines/patch-release.yml b/eng/pipelines/patch-release.yml index 36c1de66addb0..a86be5e70ec7d 100644 --- a/eng/pipelines/patch-release.yml +++ b/eng/pipelines/patch-release.yml @@ -11,6 +11,8 @@ extends: template: /eng/pipelines/templates/stages/archetype-sdk-client-patch.yml parameters: TestPipeline: ${{ parameters.TestPipeline }} + PatchMergeBack: true + PatchChangelogPath: patch-changelog.md artifacts: - name: azure-sdk-template groupId: com.azure @@ -42,4 +44,3 @@ extends: safeName: azuresdktemplatethree skipPublishDocMs: true ServiceDirectory: template-v2 - diff --git a/eng/pipelines/templates/stages/archetype-java-release-patch.yml b/eng/pipelines/templates/stages/archetype-java-release-patch.yml index 12783f080ea2b..e3d7f85c44335 100644 --- a/eng/pipelines/templates/stages/archetype-java-release-patch.yml +++ b/eng/pipelines/templates/stages/archetype-java-release-patch.yml @@ -7,6 +7,12 @@ parameters: - name: TestPipeline type: boolean default: false + - name: PatchMergeBack + type: boolean + default: false + - name: PatchChangelogPath + type: string + default: patch-changelog.md # A different environment will be passed in for service directories that have # live tests enabled for release and ReleaseDependsOnLiveTests is false - name: Environment @@ -194,7 +200,10 @@ stages: SourceRootPath: $(Pipeline.Workspace)/azure-sdk-for-java - job: UpdatePackageVersion - displayName: "Update Package Version" + ${{ if eq(parameters.PatchMergeBack, true) }}: + displayName: "Create Patch Merge-back" + ${{ else }}: + displayName: "Update Package Version" condition: and(succeeded(), ne(variables['Skip.UpdatePackageVersion'], 'true')) dependsOn: PublishESRPPackage variables: @@ -221,29 +230,50 @@ stages: inputs: versionSpec: $(PythonVersion) - # Apply the version increment to each library, which only updates the version_client.txt file, - # and then call to update_versions will then apply all the updates. - - pwsh: | - $ArtifactsList = $('$(ArtifactsJson)' | ConvertFrom-Json | Select-Object name, groupId) - $ArtifactsList | Format-Table -Property GroupId, Name | Out-String | Write-Host - python --version - foreach($artifact in $ArtifactsList) { - python eng/versioning/set_versions.py --increment-version --ai $($artifact.name) --gi $($artifact.groupId) - } - displayName: Increment package versions + - ${{ if eq(parameters.PatchMergeBack, true) }}: + - pwsh: | + $expectedArtifacts = $('$(ArtifactsJson)' | ConvertFrom-Json | ForEach-Object { "$($_.groupId):$($_.name)" }) + $(Build.SourcesDirectory)/eng/scripts/Create-Patch-Mergeback.ps1 ` + -ReleaseBranch "$(Build.SourceVersion)" ` + -BaseBranch main ` + -PatchChangelogPath "${{ parameters.PatchChangelogPath }}" ` + -ExpectedArtifacts $expectedArtifacts + displayName: 'Prepare patch merge-back against main' + + - template: /eng/common/pipelines/templates/steps/create-pull-request.yml + parameters: + BaseBranchName: refs/heads/main + PRBranchName: merge-back-patch-release-$(Build.SourceBranchName)-$(Build.BuildId) + CommitMsg: "Merge back patch release $(Build.SourceBranchName)" + PRTitle: "Merge back patch release $(Build.SourceBranchName)" + PRBody: "Promotes released patch dependency versions, inserts the prepared patch changelog entries, and regenerates pom.xml files. Source resets and README changes are intentionally excluded." + CloseAfterOpenForTesting: '${{ parameters.TestPipeline }}' + AuthToken: '' + + - ${{ else }}: + # Apply the version increment to each library, which only updates the version_client.txt file, + # and then call to update_versions will then apply all the updates. + - pwsh: | + $ArtifactsList = $('$(ArtifactsJson)' | ConvertFrom-Json | Select-Object name, groupId) + $ArtifactsList | Format-Table -Property GroupId, Name | Out-String | Write-Host + python --version + foreach($artifact in $ArtifactsList) { + python eng/versioning/set_versions.py --increment-version --ai $($artifact.name) --gi $($artifact.groupId) + } + displayName: Increment package versions - - script: | - python --version - python eng/versioning/update_versions.py --auto-version-increment --skip-readme - displayName: Update pom files for incremented versions + - script: | + python --version + python eng/versioning/update_versions.py --auto-version-increment --skip-readme + displayName: Update pom files for incremented versions - - template: /eng/common/pipelines/templates/steps/create-pull-request.yml - parameters: - PRBranchName: increment-package-version-patch-release-$(Build.BuildId) - CommitMsg: "Increment package versions for patch releases" - PRTitle: "Increment versions for patch releases" - CloseAfterOpenForTesting: '${{ parameters.TestPipeline }}' - AuthToken: '' + - template: /eng/common/pipelines/templates/steps/create-pull-request.yml + parameters: + PRBranchName: increment-package-version-patch-release-$(Build.BuildId) + CommitMsg: "Increment package versions for patch releases" + PRTitle: "Increment versions for patch releases" + CloseAfterOpenForTesting: '${{ parameters.TestPipeline }}' + AuthToken: '' - job: PublishDocsMs displayName: Docs.MS Release diff --git a/eng/pipelines/templates/stages/archetype-sdk-client-patch.yml b/eng/pipelines/templates/stages/archetype-sdk-client-patch.yml index 72739771beb75..9cf504cbbaf66 100644 --- a/eng/pipelines/templates/stages/archetype-sdk-client-patch.yml +++ b/eng/pipelines/templates/stages/archetype-sdk-client-patch.yml @@ -17,6 +17,12 @@ parameters: - name: TestPipeline type: boolean default: false +- name: PatchMergeBack + type: boolean + default: false +- name: PatchChangelogPath + type: string + default: patch-changelog.md extends: template: /eng/pipelines/templates/stages/1es-redirect.yml @@ -55,9 +61,32 @@ extends: env: AGENT_SOURCE_CHECKOUT_QUIET: 'true' - - template: /eng/pipelines/templates/steps/generate-project-list-and-cache-maven-repository.yml - parameters: - JobType: 'Build' + - ${{ if eq(parameters.PatchMergeBack, true) }}: + - pwsh: | + $validationRoot = Join-Path "$(Agent.TempDirectory)" "patch-mergeback-validation-$(System.JobAttempt)" + try { + git worktree add --detach $validationRoot "$(Build.SourceVersion)" + if ($LASTEXITCODE -ne 0) { + throw "Could not create patch merge-back validation worktree." + } + + $expectedArtifacts = $('$(ArtifactsJson)' | ConvertFrom-Json | ForEach-Object { "$($_.groupId):$($_.name)" }) + $(Build.SourcesDirectory)/eng/scripts/Create-Patch-Mergeback.ps1 ` + -RepoRoot $validationRoot ` + -ReleaseBranch "$(Build.SourceVersion)" ` + -BaseBranch main ` + -PatchChangelogPath "${{ parameters.PatchChangelogPath }}" ` + -ExpectedArtifacts $expectedArtifacts + } finally { + if (Test-Path -LiteralPath $validationRoot) { + git worktree remove --force $validationRoot + } + } + displayName: 'Dry run patch merge-back against main' + + - template: /eng/pipelines/templates/steps/generate-project-list-and-cache-maven-repository.yml + parameters: + JobType: 'Build' - template: /eng/common/pipelines/templates/steps/set-test-pipeline-version.yml parameters: @@ -315,3 +344,5 @@ extends: - Build Artifacts: ${{ parameters.Artifacts }} TestPipeline: ${{ parameters.TestPipeline }} + PatchMergeBack: ${{ parameters.PatchMergeBack }} + PatchChangelogPath: ${{ parameters.PatchChangelogPath }} diff --git a/eng/scripts/Create-Patch-Mergeback.ps1 b/eng/scripts/Create-Patch-Mergeback.ps1 index be57875aa893f..953e0840afb41 100644 --- a/eng/scripts/Create-Patch-Mergeback.ps1 +++ b/eng/scripts/Create-Patch-Mergeback.ps1 @@ -6,44 +6,15 @@ <# .SYNOPSIS -[Experimental] Automates creation of a patch-release mergeback against the current branch. +Creates the version, changelog, and generated POM changes for a patch merge-back. .DESCRIPTION -[Experimental] Given a release branch (e.g. release/patch/20260505) that contains a patch -release, this script ports the patch's published-version bumps and changelog -entries back into the current working branch. It performs three steps: - - 1. version_client.txt: For every line whose dependency-version (middle - column) was bumped on the release branch, copy that bumped value into - the current branch's version_client.txt. The current-version (right - column) on the current branch is preserved as-is, because it usually - reflects in-development beta versions that should not be reverted. - - 2. CHANGELOG.md: For each library whose dependency-version changed, take - the topmost (newest) entry from the release branch's CHANGELOG and - insert it into the current branch's CHANGELOG. When an existing - "## ... (Unreleased)" section is present, the new entry is inserted - after that entire section (before the next "##" heading). Otherwise, - it is inserted before the first dated entry (immediately after the - "# Release History" heading). - - 3. Runs `python eng/versioning/update_versions.py --skip-readme` to - propagate the new dependency-versions into all pom.xml files. - -This script does NOT commit, push, or open a pull request. Review the -working tree afterwards, then commit and push manually. - -.PARAMETER ReleaseBranch -The name of the patch release branch to port edits from -(for example release/patch/20260505). The branch can be local or remote; -the script will use `git fetch` and resolve origin/ if needed. - -.PARAMETER RepoRoot -Optional. Path to the azure-sdk-for-java clone. Defaults to the repo root -inferred from the script's location. - -.EXAMPLE -.\eng\scripts\Create-Patch-Mergeback.ps1 -ReleaseBranch release/patch/20260505 +Reads patch-changelog.md and version_client.txt from a patch release branch, +checks out the requested base branch, promotes released patch versions into the +base branch dependency-version column without changing current-version, inserts +the exact patch changelog entries, and regenerates POM files. + +The script does not commit, push, or create a pull request. #> [CmdletBinding()] @@ -51,289 +22,165 @@ param( [Parameter(Mandatory = $true)] [string]$ReleaseBranch, + [string]$BaseBranch = 'main', + + [string]$PatchChangelogPath = 'patch-changelog.md', + + [string[]]$ExpectedArtifacts = @(), + [string]$RepoRoot ) $ErrorActionPreference = 'Stop' -# Resolve repo root. if (-not $RepoRoot) { $RepoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..') } $RepoRoot = (Resolve-Path $RepoRoot).Path -Push-Location $RepoRoot -try { - Write-Host "Repo root: $RepoRoot" - $workingTreeStatus = git status --porcelain - if ($LASTEXITCODE -ne 0) { - throw "Failed to check working tree status." - } - if ($workingTreeStatus) { - throw "Working tree is not clean. Commit, stash, or discard local changes before running this script." - } +. (Join-Path $PSScriptRoot 'patch-mergeback-helpers.ps1') - # --------------------------------------------------------------------- - # Resolve the release branch ref. - # --------------------------------------------------------------------- - Write-Host "Fetching latest refs..." - git fetch --quiet origin 2>$null | Out-Null +function Invoke-Git { + param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Arguments) - $branchRef = $null - foreach ($candidate in @($ReleaseBranch, "origin/$ReleaseBranch")) { - $null = git rev-parse --verify --quiet "$candidate" 2>$null - if ($LASTEXITCODE -eq 0) { $branchRef = $candidate; break } - } - if (-not $branchRef) { - throw "Could not resolve '$ReleaseBranch' (tried local and origin/)." - } - Write-Host "Using release branch ref: $branchRef" - - # --------------------------------------------------------------------- - # 1. version_client.txt: port dependency-version bumps. - # --------------------------------------------------------------------- - $vcRelPath = 'eng/versioning/version_client.txt' - $vcPath = Join-Path $RepoRoot $vcRelPath - - Write-Host "`n[1/3] Porting dependency-version bumps from $vcRelPath ..." - - $releaseVcRaw = git show "${branchRef}:${vcRelPath}" - if ($LASTEXITCODE -ne 0) { throw "Failed to read $vcRelPath from $branchRef." } - $releaseLines = $releaseVcRaw -split "`r?`n" - $localLines = Get-Content -LiteralPath $vcPath - - function Parse-VcLine([string]$line) { - # Returns @{ Key=...; Dep=...; Cur=...; Comment=... } or $null - if ([string]::IsNullOrWhiteSpace($line)) { return $null } - $trim = $line.TrimStart() - if ($trim.StartsWith('#')) { return $null } - # Strip optional inline comment. - $body = $line - $note = '' - $hash = $line.IndexOf(' #') - if ($hash -ge 0) { - $body = $line.Substring(0, $hash) - $note = $line.Substring($hash) - } - $parts = $body.Split(';') - if ($parts.Count -lt 3) { return $null } - return [pscustomobject]@{ - Key = $parts[0].Trim() - Dep = $parts[1].Trim() - Cur = $parts[2].Trim() - Comment = $note - } + & git @Arguments + if ($LASTEXITCODE -ne 0) { + throw "git $($Arguments -join ' ') failed with exit code $LASTEXITCODE." } +} - $releaseMap = @{} - foreach ($l in $releaseLines) { - $p = Parse-VcLine $l - if ($p) { $releaseMap[$p.Key] = $p } +Push-Location $RepoRoot +try { + if (git status --porcelain) { + throw 'Working tree is not clean. Commit, stash, or discard local changes before creating a merge-back.' } - $changedArtifacts = New-Object System.Collections.Generic.List[string] - $newLocal = New-Object System.Collections.Generic.List[string] + $baseBranchName = $BaseBranch -replace '^refs/heads/', '' -replace '^origin/', '' - foreach ($line in $localLines) { - $p = Parse-VcLine $line - if (-not $p -or -not $releaseMap.ContainsKey($p.Key)) { - $newLocal.Add($line); continue - } - $r = $releaseMap[$p.Key] - if ($r.Dep -eq $p.Dep) { - $newLocal.Add($line); continue - } - # Bump dep-version, keep local current-version. - $newBody = "$($p.Key);$($r.Dep);$($p.Cur)" - $newLocal.Add("$newBody$($p.Comment)") - $changedArtifacts.Add($p.Key) | Out-Null - } + Invoke-Git fetch --quiet origin $baseBranchName - if ($changedArtifacts.Count -eq 0) { - Write-Host " No dependency-version changes found. Nothing to port." - return + if ($ReleaseBranch -match '^[0-9a-fA-F]{40}$') { + $releaseRef = $ReleaseBranch + } else { + $releaseBranchName = $ReleaseBranch -replace '^refs/heads/', '' -replace '^origin/', '' + Invoke-Git fetch --quiet origin $releaseBranchName + $releaseRef = "origin/$releaseBranchName" } + $baseRef = "origin/$baseBranchName" - # Preserve original line endings of the file. - $origBytes = [System.IO.File]::ReadAllBytes($vcPath) - $useCrlf = $false - for ($i = 0; $i -lt [Math]::Min($origBytes.Length, 4096); $i++) { - if ($origBytes[$i] -eq 13) { $useCrlf = $true; break } - } - $eol = if ($useCrlf) { "`r`n" } else { "`n" } - [System.IO.File]::WriteAllText($vcPath, ($newLocal -join $eol) + $eol) - - Write-Host " Bumped $($changedArtifacts.Count) artifact(s) in version_client.txt." - - # --------------------------------------------------------------------- - # 2. CHANGELOG.md: port the latest entry from the release branch for - # each artifact whose dependency-version changed. - # --------------------------------------------------------------------- - Write-Host "`n[2/3] Porting CHANGELOG.md entries..." - - # Build artifactId -> list of CHANGELOG.md paths once. - $changelogIndex = @{} - Get-ChildItem -Path (Join-Path $RepoRoot 'sdk') -Recurse -Filter 'CHANGELOG.md' -File ` - | ForEach-Object { - $artifactId = $_.Directory.Name - if (-not $changelogIndex.ContainsKey($artifactId)) { - $changelogIndex[$artifactId] = New-Object System.Collections.Generic.List[string] - } - $changelogIndex[$artifactId].Add($_.FullName) | Out-Null - } + Invoke-Git rev-parse --verify $releaseRef + Invoke-Git rev-parse --verify $baseRef - function Resolve-ChangelogPath([string]$artifactId) { - if (-not $changelogIndex.ContainsKey($artifactId)) { return $null } - $paths = $changelogIndex[$artifactId] - if ($paths.Count -eq 1) { return $paths[0] } - # Prefer the v1 (non *-v2) directory, then shortest path as a tiebreaker. - $nonV2 = $paths | Where-Object { $_ -notmatch '[\\/][^\\/]*-v2[\\/]' } - if ($nonV2.Count -eq 1) { return $nonV2[0] } - return ($paths | Sort-Object Length | Select-Object -First 1) + $manifestContent = git show "${releaseRef}:${PatchChangelogPath}" + if ($LASTEXITCODE -ne 0) { + throw "Could not read '$PatchChangelogPath' from '$releaseRef'." } + $entries = ConvertFrom-PatchChangelog -Content ($manifestContent -join "`n") - function Get-LatestChangelogEntry([string]$relPath) { - # Returns @{ Header=...; Body=... } for the topmost ## entry, or $null. - $raw = git show "${branchRef}:${relPath}" 2>$null - if ($LASTEXITCODE -ne 0 -or -not $raw) { return $null } - $lines = $raw -split "`r?`n" - $startIdx = -1 - for ($i = 0; $i -lt $lines.Count; $i++) { - if ($lines[$i] -match '^##\s+\S') { $startIdx = $i; break } - } - if ($startIdx -lt 0) { return $null } - $endIdx = $lines.Count - for ($i = $startIdx + 1; $i -lt $lines.Count; $i++) { - if ($lines[$i] -match '^##\s+\S') { $endIdx = $i; break } + $releaseVersionContent = git show "${releaseRef}:eng/versioning/version_client.txt" + if ($LASTEXITCODE -ne 0) { + throw "Could not read eng/versioning/version_client.txt from '$releaseRef'." + } + $releaseVersions = @{} + foreach ($line in $releaseVersionContent) { + $parsed = ConvertFrom-VersionClientLine -Line $line + if ($parsed) { + $releaseVersions[$parsed.Artifact] = $parsed } - # Trim trailing blank lines. - $block = $lines[$startIdx..($endIdx - 1)] - while ($block.Count -gt 0 -and [string]::IsNullOrWhiteSpace($block[-1])) { - $block = $block[0..($block.Count - 2)] + } + foreach ($entry in $entries) { + if (-not $releaseVersions.ContainsKey($entry.Artifact)) { + throw "Manifest artifact '$($entry.Artifact)' was not found on '$releaseRef'." } - return [pscustomobject]@{ - Header = $lines[$startIdx] - Body = ($block -join "`n") + if ($releaseVersions[$entry.Artifact].CurrentVersion -ne $entry.Version) { + throw "Manifest version '$($entry.Version)' for '$($entry.Artifact)' does not match release current-version '$($releaseVersions[$entry.Artifact].CurrentVersion)'." } } - $portedCount = 0 - $skippedNoFile = New-Object System.Collections.Generic.List[string] - $skippedNoEntry = New-Object System.Collections.Generic.List[string] - $alreadyPresent = New-Object System.Collections.Generic.List[string] - - foreach ($key in $changedArtifacts) { - $artifactId = $key.Split(':')[1] - $localPath = Resolve-ChangelogPath $artifactId - if (-not $localPath) { $skippedNoFile.Add($artifactId) | Out-Null; continue } - - $relLocalPath = (Resolve-Path -LiteralPath $localPath -Relative).TrimStart('.', '\', '/').Replace('\', '/') - - $entry = Get-LatestChangelogEntry $relLocalPath - if (-not $entry) { $skippedNoEntry.Add($artifactId) | Out-Null; continue } - - $existing = Get-Content -LiteralPath $localPath -Raw - # Skip if the same released-version header is already present. - $headerEscaped = [regex]::Escape($entry.Header) - if ($existing -match "(?m)^$headerEscaped\s*$") { - $alreadyPresent.Add($artifactId) | Out-Null; continue + if ($ExpectedArtifacts.Count -gt 0) { + $expectedSet = @{} + foreach ($artifact in $ExpectedArtifacts) { + if ($expectedSet.ContainsKey($artifact)) { + throw "Expected artifact list contains duplicate '$artifact'." + } + $expectedSet[$artifact] = $true } - $existingLines = $existing -split "`r?`n" + $manifestSet = @{} + foreach ($entry in $entries) { + $manifestSet[$entry.Artifact] = $true + } - # Find an Unreleased heading; if none, find the first dated heading. - $unreleasedIdx = -1 - $firstDatedIdx = -1 - for ($i = 0; $i -lt $existingLines.Count; $i++) { - if ($unreleasedIdx -lt 0 -and $existingLines[$i] -match '^##\s+.*\(Unreleased\)\s*$') { - $unreleasedIdx = $i - } elseif ($firstDatedIdx -lt 0 -and $existingLines[$i] -match '^##\s+\S') { - $firstDatedIdx = $i - } + $missing = @($expectedSet.Keys | Where-Object { -not $manifestSet.ContainsKey($_) }) + $unexpectedEntries = @($manifestSet.Keys | Where-Object { -not $expectedSet.ContainsKey($_) }) + if ($missing.Count -gt 0 -or $unexpectedEntries.Count -gt 0) { + throw "Patch changelog artifact set does not match the release artifacts. Missing: $($missing -join ', '). Unexpected: $($unexpectedEntries -join ', ')." } + } - $insertText = $entry.Body.TrimEnd() + "`n" + Invoke-Git checkout --detach $baseRef - if ($unreleasedIdx -ge 0) { - # Find end of the Unreleased block (next ## heading or EOF). - $blockEnd = $existingLines.Count - for ($i = $unreleasedIdx + 1; $i -lt $existingLines.Count; $i++) { - if ($existingLines[$i] -match '^##\s+\S') { $blockEnd = $i; break } - } - # Strip trailing blanks inside the unreleased block before inserting. - $tail = $blockEnd - while ($tail -gt $unreleasedIdx + 1 -and [string]::IsNullOrWhiteSpace($existingLines[$tail - 1])) { - $tail-- - } - $before = if ($tail -gt 0) { $existingLines[0..($tail - 1)] } else { @() } - $after = if ($blockEnd -lt $existingLines.Count) { $existingLines[$blockEnd..($existingLines.Count - 1)] } else { @() } - $merged = @() - $merged += $before - $merged += '' - $merged += ($insertText -split "`n") - if ($after.Count -gt 0) { $merged += $after } - } elseif ($firstDatedIdx -ge 0) { - $before = $existingLines[0..($firstDatedIdx - 1)] - $after = $existingLines[$firstDatedIdx..($existingLines.Count - 1)] - # Ensure exactly one blank between. - while ($before.Count -gt 0 -and [string]::IsNullOrWhiteSpace($before[-1])) { - $before = $before[0..($before.Count - 2)] - } - $merged = @() - $merged += $before - $merged += '' - $merged += ($insertText -split "`n") - $merged += '' - $merged += $after - } else { - # No headings at all; append. - $merged = $existingLines + @('') + ($insertText -split "`n") - } + $versionClientPath = Join-Path $RepoRoot 'eng/versioning/version_client.txt' + $versionLines = Get-Content -LiteralPath $versionClientPath + $updatedVersionLines = Update-VersionClientForPatch -Lines $versionLines -Entries $entries + $versionEol = if ((Get-Content -LiteralPath $versionClientPath -Raw).Contains("`r`n")) { "`r`n" } else { "`n" } + [System.IO.File]::WriteAllText($versionClientPath, ($updatedVersionLines -join $versionEol) + $versionEol) - # Determine line ending of the existing file. - $crlf = $existing.Contains("`r`n") - $eol2 = if ($crlf) { "`r`n" } else { "`n" } - $finalText = ($merged -join $eol2) - if (-not $finalText.EndsWith($eol2)) { $finalText += $eol2 } - [System.IO.File]::WriteAllText($localPath, $finalText) - $portedCount++ + foreach ($entry in $entries) { + $changelogPath = Join-Path $RepoRoot $entry.Path + if (-not (Test-Path -LiteralPath $changelogPath)) { + throw "Target changelog '$($entry.Path)' does not exist on '$baseRef'." + } + $content = Get-Content -LiteralPath $changelogPath -Raw + $updatedContent = Add-PatchChangelogEntry -Content $content -Entry $entry + if ($updatedContent -ne $content) { + [System.IO.File]::WriteAllText($changelogPath, $updatedContent) + } } - Write-Host " Ported $portedCount changelog entr$(if ($portedCount -eq 1){'y'}else{'ies'})." - if ($alreadyPresent.Count -gt 0) { - Write-Host " Already present (skipped): $($alreadyPresent -join ', ')" + $python = (Get-Command python -ErrorAction SilentlyContinue) ?? (Get-Command python3 -ErrorAction SilentlyContinue) + if (-not $python) { + throw 'python is not on PATH; cannot run update_versions.py.' } - if ($skippedNoFile.Count -gt 0) { - Write-Warning " No CHANGELOG.md found for: $($skippedNoFile -join ', ')" + & $python.Source 'eng/versioning/update_versions.py' '--skip-readme' + if ($LASTEXITCODE -ne 0) { + throw "update_versions.py failed with exit code $LASTEXITCODE." } - if ($skippedNoEntry.Count -gt 0) { - Write-Warning " No release entry found on $branchRef for: $($skippedNoEntry -join ', ')" + + $allowedChangelogs = @{} + foreach ($entry in $entries) { + $allowedChangelogs[$entry.Path] = $true } - # --------------------------------------------------------------------- - # 3. Propagate dependency-versions into pom.xml files. - # --------------------------------------------------------------------- - Write-Host "`n[3/3] Running update_versions.py --skip-readme ..." - $py = (Get-Command python -ErrorAction SilentlyContinue) ?? (Get-Command python3 -ErrorAction SilentlyContinue) - if (-not $py) { throw "python is not on PATH; cannot run update_versions.py." } - & $py.Source 'eng/versioning/update_versions.py' '--skip-readme' + $unexpected = [System.Collections.Generic.List[string]]::new() + $statusLines = @(git status --porcelain) if ($LASTEXITCODE -ne 0) { - throw "update_versions.py failed with exit code $LASTEXITCODE." + throw 'Failed to inspect the merge-back working tree.' + } + foreach ($statusLine in $statusLines) { + $path = $statusLine.Substring(3).Replace('\', '/') + if ( + $path -eq 'eng/versioning/version_client.txt' -or + $path -match '(^|/)pom\.xml$' -or + $allowedChangelogs.ContainsKey($path) + ) { + continue + } + $unexpected.Add($path) } - # --------------------------------------------------------------------- - # Summary. - # --------------------------------------------------------------------- - $status = git status --porcelain - $clCount = ($status | Where-Object { $_ -match 'CHANGELOG\.md' }).Count - $pomCount = ($status | Where-Object { $_ -match 'pom\.xml' }).Count - - Write-Host "`nDone." - Write-Host " version_client.txt artifacts bumped : $($changedArtifacts.Count)" - Write-Host " CHANGELOG.md files modified : $clCount" - Write-Host " pom.xml files modified : $pomCount" - Write-Host "`nReview with 'git diff', then commit and push when ready." -} -finally { + if ($unexpected.Count -gt 0) { + throw "Merge-back produced unsupported file changes: $($unexpected -join ', ')." + } + if ($statusLines | Where-Object { $_ -match 'README\.md$' }) { + throw 'Merge-back must not modify README.md files.' + } + + $changelogCount = @($statusLines | Where-Object { $_ -match 'CHANGELOG\.md$' }).Count + $pomCount = @($statusLines | Where-Object { $_ -match 'pom\.xml$' }).Count + Write-Host "Prepared merge-back for $($entries.Count) patch artifact(s)." + Write-Host "Modified changelogs: $changelogCount" + Write-Host "Generated POM changes: $pomCount" +} finally { Pop-Location } diff --git a/eng/scripts/New-PatchChangelog.ps1 b/eng/scripts/New-PatchChangelog.ps1 new file mode 100644 index 0000000000000..8713b8bde6fb9 --- /dev/null +++ b/eng/scripts/New-PatchChangelog.ps1 @@ -0,0 +1,79 @@ +#Requires -Version 7.0 +#Requires -PSEdition Core + +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. + +[CmdletBinding()] +param( + [string]$PackagesYmlPath = 'eng/pipelines/patch-release.yml', + [string]$OutputPath = 'patch-changelog.md', + [string]$RepoRoot +) + +$ErrorActionPreference = 'Stop' + +if (-not $RepoRoot) { + $RepoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..') +} +$RepoRoot = (Resolve-Path $RepoRoot).Path + +. (Join-Path $PSScriptRoot 'patch-mergeback-helpers.ps1') +. (Join-Path $RepoRoot 'eng/common/scripts/Helpers/PSModule-Helpers.ps1') +Install-ModuleIfNotInstalled 'powershell-yaml' '0.4.7' | Import-Module + +$packagesPath = Join-Path $RepoRoot $PackagesYmlPath +$outputFile = Join-Path $RepoRoot $OutputPath +$versionClientPath = Join-Path $RepoRoot 'eng/versioning/version_client.txt' + +$yml = Get-Content -LiteralPath $packagesPath -Raw | ConvertFrom-Yaml -Ordered +$artifacts = @($yml['extends']['parameters']['artifacts']) +if ($artifacts.Count -eq 0) { + if (Test-Path -LiteralPath $outputFile) { + Remove-Item -LiteralPath $outputFile + } + Write-Host "No patch artifacts were found in '$PackagesYmlPath'. No patch changelog was generated." + return +} + +$versionMap = @{} +foreach ($line in Get-Content -LiteralPath $versionClientPath) { + $parsed = ConvertFrom-VersionClientLine -Line $line + if ($parsed) { + $versionMap[$parsed.Artifact] = $parsed + } +} + +$entries = [System.Collections.Generic.List[object]]::new() +foreach ($artifact in $artifacts) { + $coordinate = "$($artifact.groupId):$($artifact.name)" + if (-not $versionMap.ContainsKey($coordinate)) { + throw "Artifact '$coordinate' was not found in eng/versioning/version_client.txt." + } + + $serviceDirectory = $artifact.ServiceDirectory.ToString().TrimEnd('/', '\') + $relativePackagePath = if ((Split-Path $serviceDirectory -Leaf) -eq $artifact.name) { + $serviceDirectory + } else { + "$serviceDirectory/$($artifact.name)" + } + $relativePath = "sdk/$relativePackagePath/CHANGELOG.md" + $changelogPath = Join-Path $RepoRoot $relativePath + if (-not (Test-Path -LiteralPath $changelogPath)) { + throw "Changelog '$relativePath' was not found for '$coordinate'." + } + + $version = $versionMap[$coordinate].CurrentVersion + $changelogContent = Get-Content -LiteralPath $changelogPath -Raw + $entry = Get-ChangelogEntry -Content $changelogContent -Version $version + $entryContent = Resolve-PatchDependencyVersions -ChangelogContent $changelogContent -Entry $entry + $entries.Add([pscustomobject]@{ + Artifact = $coordinate + Path = $relativePath + Version = $version + Content = $entryContent + }) +} + +[System.IO.File]::WriteAllText($outputFile, (New-PatchChangelogContent -Entries $entries)) +Write-Host "Wrote $($entries.Count) patch changelog entries to '$OutputPath'." diff --git a/eng/scripts/patch-mergeback-helpers.ps1 b/eng/scripts/patch-mergeback-helpers.ps1 new file mode 100644 index 0000000000000..640f65eeaebe4 --- /dev/null +++ b/eng/scripts/patch-mergeback-helpers.ps1 @@ -0,0 +1,331 @@ +# Copyright (c) Microsoft Corporation. All rights reserved. +# Licensed under the MIT License. + +$script:PatchChangelogStartMarker = '' + +function ConvertFrom-VersionClientLine { + param([string]$Line) + + if ([string]::IsNullOrWhiteSpace($Line) -or $Line.TrimStart().StartsWith('#')) { + return $null + } + + $body = $Line + $comment = '' + $commentIndex = $Line.IndexOf(' #') + if ($commentIndex -ge 0) { + $body = $Line.Substring(0, $commentIndex) + $comment = $Line.Substring($commentIndex) + } + + $parts = $body.Split(';') + if ($parts.Count -ne 3) { + return $null + } + + return [pscustomobject]@{ + Artifact = $parts[0].Trim() + DependencyVersion = $parts[1].Trim() + CurrentVersion = $parts[2].Trim() + Comment = $comment + } +} + +function ConvertTo-ComparableVersion { + param([Parameter(Mandatory = $true)][string]$Version) + + if ($Version -notmatch '^(?\d+)\.(?\d+)\.(?\d+)(?:-(?