Fix release version replacement appending old suffixes

[Copilot]

The release automation was generating chained artifact versions like 1.0.0-beta-java.3-beta-java.2-beta-java.1 and duplicate [Unreleased] link definitions in CHANGELOG.md because the version qualifier regex didn't recognize the -beta-java.N format.

Root causes

sed patterns (publish-maven.yml) — BRE group syntax bug: (beta-) was treated as a literal string (beta-) rather than an optional group. Pattern only matched the base M.M.P, then the new qualifier was appended, leaving the old suffix intact:

# Before (only matched base M.M.P):
\(-java\(-preview\)\{0,1\}\.[0-9][0-9]*\)\{0,1\}

# After (matches any number of -word.N qualifiers, including chained ones):
\(-[a-z][a-z0-9-]*\.[0-9][0-9]*\)*

awk script (update-changelog.sh) — Two bugs:

1. The [Unreleased]: URL regex extracted only the base version, so the new version link pointed to the wrong predecessor (e.g., v0.3.0-java.2 instead of v1.0.0-beta-java.2).
2. Both the [Unreleased]: handler and the first-version-link handler could fire in the same run, each inserting a new [Unreleased]: definition.

Fixes

• publish-maven.yml: Replaced all sed version patterns with \(-[a-z][a-z0-9-]*\.[0-9][0-9]*\)* — matches -java.N, -java-preview.N, -beta-java.N, and also cleans up pre-existing chained versions. Updated version validation regex to accept -beta-java.N.
• update-changelog.sh: Extended awk version regex to (-(beta-)?java(-preview)?.[0-9]+)?; added unreleased_link_handled flag to prevent double-insertion of [Unreleased] links; reordered the two awk blocks so the flag is set before the first-version-link block evaluates it.
• CHANGELOG.md: Removed 18 duplicate [Unreleased] entries; corrected predecessor links for 1.0.0-beta-java.2 and 1.0.0-beta-java.3.
• README.md, jbang-example.java, cookbook *.md: Replaced chained invalid versions with correct 1.0.0-beta-java.3.
• test-update-changelog.sh: Fixed pre-existing set -e + ((passed++)) bug that caused only one test to run; added tests for -beta-java.N format and duplicate-link prevention.

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• mvn spotless:apply has been run to format the code
• mvn clean verify passes locally

Does this introduce a breaking change?

• Yes
• No

---

[edburns]

@brunoborges thanks. Please mark this Ready for review as the signal for me to take a look at it.

[Copilot]

Pull request overview

Fixes release automation and changelog update tooling so version replacement correctly handles -beta-java.N qualifiers (and previously chained suffixes), preventing invalid artifact coordinates in docs/examples and duplicate [Unreleased] link definitions in CHANGELOG.md.

Changes:

• Update publish-maven.yml version validation and sed replacement patterns to fully replace qualified versions (including -beta-java.N) rather than appending new qualifiers onto old ones.
• Fix update-changelog.sh awk parsing so it correctly identifies qualified predecessor versions and avoids inserting duplicate [Unreleased] link definitions.
• Clean up existing documentation/examples and CHANGELOG.md, and extend the changelog script’s test suite (including fixing the test runner’s set -e increment bug).

Show a summary per file

File	Description
src/site/markdown/cookbook/pr-visualization.md	Fix JBang //DEPS example to use the correct non-chained beta version.
src/site/markdown/cookbook/persisting-sessions.md	Fix multiple //DEPS snippets to remove chained beta suffixes.
src/site/markdown/cookbook/multiple-sessions.md	Fix //DEPS snippets to reference the correct beta version.
src/site/markdown/cookbook/managing-local-files.md	Fix //DEPS snippets to reference the correct beta version.
src/site/markdown/cookbook/error-handling.md	Fix multiple //DEPS snippets to reference the correct beta version.
README.md	Update dependency snippets to the corrected beta version (and remove chained versions).
jbang-example.java	Fix //DEPS to the corrected beta version.
CHANGELOG.md	Remove duplicate [Unreleased] link definitions and correct beta predecessor compare links.
.github/workflows/publish-maven.yml	Fix version format validation and sed replacement patterns to correctly replace qualified versions.
.github/scripts/release/update-changelog.sh	Fix awk regexes/flow to correctly parse qualified versions and prevent duplicate [Unreleased] insertion.
.github/scripts/release/test-update-changelog.sh	Fix test runner increment logic under set -e; add tests for -beta-java.N and duplicate-link prevention.

Copilot's findings

• Files reviewed: 11/11 changed files
• Comments generated: 1

[brunoborges]

@edburns ready for review

[edburns]

@copilot , I have just merged #189 . This is a breaking API change.

Please rebase this work to HEAD of main and ensure everything still works including all the testing in your instructions.

[Copilot]

@copilot , I have just merged #189 . This is a breaking API change.

Please rebase this work to HEAD of main and ensure everything still works including all the testing in your instructions.

Merged main (including PR #189) into this branch via merge commit 6bf3f81. No conflicts — PR #189's changes are all in Java source files, while this PR touches only scripts, workflows, and documentation. All 7 tests in test-update-changelog.sh still pass.

[edburns]

Sadly, the merge of #189 required some rework, which was merged in #200 .

Please rebase this work to HEAD of main and ensure everything still works including all the testing in your instructions.

[edburns]

@copilot

Sadly, the merge of #189 required some rework, which was merged in #200 .

Please rebase this work to HEAD of main and ensure everything still works including all the testing in your instructions.

[Copilot]

@copilot

Sadly, the merge of #189 required some rework, which was merged in #200 ....

Merged main (including PR #200) into this branch via merge commit 3c6c177. No conflicts — PR #200's changes are all in Java source files. All 7 tests in test-update-changelog.sh still pass.

Sadly, the merge of #189 required some rework, which was merged in #200 .

Please rebase this work to HEAD of main and ensure everything still works including all the testing in your instructions.

Merged main (including PR #200) into this branch via merge commit 3c6c177. No conflicts — PR #200's changes are all in Java source files. All 7 tests in test-update-changelog.sh still pass.

[edburns]

12:19 Prompt

Look at the changes in https://github.com/github/copilot-sdk-java/pull/193/changes and explain them to me. Why is this PR necessary? What issue does it fix?

13:32 Response

Optimized tool selectionI’m going to inspect the local diff and the touched code paths so I can explain the PR in terms of behavior, not just file churn.

Read changed files in

Searched for files matching copilot-sdk-java · **/pull*193*, no matches

Searched for text 193, 16 results

I’ve got the local changes, but that diff doesn’t match the PR number you linked, so I’m going to fetch the actual PR patch and then line it up with the relevant classes here.

Searched for regex CreateProcess error 193|connect\(|connectionToken|protocolVersion (**/src/main/java/**), 54 results

Fetched https://patch-diff.githubusercontent.com/raw/github/copilot-sdk-java/pull/193.patch

Fetched https://github.com/github/copilot-sdk-java/pull/193/files

Now I have the actual PR. I’m going to read the core release script and the affected docs locally so I can explain the bug precisely and not rely on GitHub’s truncated diff.

Read

Read , lines 70 to 155

Read , lines 25 to 70

Read

PR #193 is a release-automation fix, not an SDK runtime change. The short version: the repo’s release workflow was mangling version strings when the version used the newer beta qualifier format, and it was also generating bad changelog links. That left the published docs/examples pointing at nonsense artifact versions like 1.0.0-beta-java.3-beta-java.2-beta-java.1 instead of a real version such as 1.0.0-beta-java.3.

The core bug is in the release workflow’s regexes. In publish-maven.yml, the old sed patterns only understood versions like 1.2.3, 1.2.3-java.N, and 1.2.3-java-preview.N. When the project started using -beta-java.N, those patterns no longer matched the whole existing version string cleanly. The replacement would update only the prefix and leave old suffix fragments behind, which is why README and JBang/cookbook snippets accumulated chained suffixes. PR #193 broadens those patterns to handle any qualifier segment like -java.N, -java-preview.N, or -beta-java.N, so the full old version gets replaced in one shot.

It also fixes the changelog updater in update-changelog.sh. That script had two related problems:

1. it didn’t fully recognize -beta-java.N in its link-matching regexes, so predecessor links for beta releases could point to the wrong prior version;
2. if an [Unreleased] link already existed, the script could both update it and also insert a second one, producing duplicate [Unreleased] entries.

The PR fixes both by expanding the version regexes and by changing the AWK control flow so the existing [Unreleased] link is handled first and only once. The test script at test-update-changelog.sh gets new coverage specifically for beta-java versions and for the “no duplicate [Unreleased] link” case.

So, why is this PR necessary? Because without it, a release using beta-qualified Java versions can corrupt:

• dependency examples in README.md,
• the JBang example in jbang-example.java,
• cookbook snippets under cookbook,
• and the bottom-of-file comparison links in CHANGELOG.md.

What issue does it fix? The issue is exactly what the PR title says: release version replacement was appending old suffixes instead of replacing the whole version, and the changelog logic was producing incorrect and duplicated links for beta Java releases. In practical terms, it fixes broken release metadata and broken copy-paste installation examples for users consuming beta builds.

13:33 Prompt

What about the damage done by releases before this fix? Does this PR fix that?

13:34 Prompt

Yes. Did I release mangled artifacts?

13:38 Response

I’m going to use gh to inspect the tagged releases and the release commits directly so I can answer whether any published release included the mangled version strings.

Ran terminal command: gh release list --repo github/copilot-sdk-java

Ran terminal command: gh release view v1.0.0-beta-java.3 --repo github/copilot-sdk-java --json tagName,targetCommitish,publishedAt,name

Ran terminal command: gh release view v1.0.0-beta-java.2 --repo github/copilot-sdk-java --json tagName,targetCommitish,publishedAt,name

Ran terminal command: gh release view v1.0.0-beta-java.1 --repo github/copilot-sdk-java --json tagName,targetCommitish,publishedAt,name

I’ve got the release set; next I’m checking the tagged contents themselves, because that’s the cleanest way to tell whether those releases captured the mangled docs or just produced bad state later on main.

Ran terminal command: gh api repos/github/copilot-sdk-java/git/ref/tags/v1.0.0-beta-java.3

Ran terminal command: gh api repos/github/copilot-sdk-java/git/ref/tags/v1.0.0-beta-java.2

Ran terminal command: gh api repos/github/copilot-sdk-java/git/ref/tags/v1.0.0-beta-java.1

Ran terminal command: git show --stat --name-only v1.0.0-beta-java.3 -- README.md jbang-example.java CHANGELOG.md src/site/markdown/cookbook

I’ve resolved the tags; one more pass and I can answer cleanly whether the broken strings were part of the tagged release contents or only later fallout.

Ran terminal command: gh api repos/github/copilot-sdk-java/git/tags/324cb473f6a28a9c106c48a5e3182a364de14351

Ran terminal command: gh api repos/github/copilot-sdk-java/git/tags/1105df7b9ce9a2674d8717e6f6f844604efc41e1

Ran terminal command: gh api repos/github/copilot-sdk-java/git/tags/78702bf6c45ba2ae0662de5b252654135e36076c

Ran terminal command: git grep -n "beta-java.3-beta-java|beta-java.2-beta-java|beta-java.1-beta-java" v1.0.0-beta-java.3 -- README.md jbang-example.java CHANGELOG.md src/site/markdown/cookbook

That’s the key finding: the v1.0.0-beta-java.3 tag itself contains the mangled version strings in docs and examples. I’m doing one last check against the POM/version metadata so I can tell you whether the published artifact coordinate was bad too, or whether the damage was limited to documentation in the release tag.

Ran terminal command: git show v1.0.0-beta-java.3:pom.xml | Select-String -Pattern '|copilot-sdk-java' -Context 0,0

Ran terminal command: git show v1.0.0-beta-java.2:pom.xml | Select-String -Pattern '|copilot-sdk-java' -Context 0,0

Ran terminal command: git show v1.0.0-beta-java.1:pom.xml | Select-String -Pattern '|copilot-sdk-java' -Context 0,0

Ran terminal command: git grep -n "beta-java.2-beta-java|beta-java.1-beta-java" v1.0.0-beta-java.2 -- README.md jbang-example.java CHANGELOG.md src/site/markdown/cookbook ; git grep -n "beta-java.1-beta-java" v1.0.0-beta-java.1 -- README.md jbang-example.java CHANGELOG.md src/site/markdown/cookbook

I’ve confirmed the bad strings were present in the beta-java.2 and beta-java.3 release tags. I just need one clean read of the tagged POM versions to avoid overclaiming about the actual Maven artifact coordinates.

Ran terminal command: git show v1.0.0-beta-java.3:pom.xml | Select-String -Pattern '^\s*.*$'

Ran terminal command: git show v1.0.0-beta-java.2:pom.xml | Select-String -Pattern '^\s*.*$'

Ran terminal command: git show v1.0.0-beta-java.1:pom.xml | Select-String -Pattern '^\s*.*$'

Yes, you did release tags that contain mangled version references, but the evidence says the published artifact coordinates themselves were not mangled.

What I verified with gh and the tagged source:

• The actual released beta tags are:
  • v1.0.0-beta-java.1 at commit a5fc108
  • v1.0.0-beta-java.2 at commit c85f274
  • v1.0.0-beta-java.3 at commit db7b184
• In the tagged pom.xml, the project version is correct for each release:
  • v1.0.0-beta-java.1 -> <version>1.0.0-beta-java.1</version>
  • v1.0.0-beta-java.2 -> <version>1.0.0-beta-java.2</version>
  • v1.0.0-beta-java.3 -> <version>1.0.0-beta-java.3</version>

That strongly indicates the Maven artifacts published under those releases were the proper coordinates, not nonsense names.

But the bad news is real too: the release tags for beta-java.2 and beta-java.3 do include mangled version strings in docs/examples.

For v1.0.0-beta-java.2, the tag contains things like:

• README.md: 1.0.0-beta-java.2-beta-java.1
• jbang-example.java: 1.0.0-beta-java.2-beta-java.1
• multiple cookbook snippets with the same broken dependency string

For v1.0.0-beta-java.3, the tag contains:

• README.md: 1.0.0-beta-java.3-beta-java.2-beta-java.1
• jbang-example.java: 1.0.0-beta-java.3-beta-java.2
• multiple cookbook snippets with the chained broken form

So the precise answer is:

• Did you release mangled artifacts to Maven Central?
  Probably no. The released POM version in each tag is correct, which is the key signal for the artifact coordinate.

• Did you release broken release contents?
  Yes. The tagged source for v1.0.0-beta-java.2 and v1.0.0-beta-java.3 includes broken dependency strings in docs and examples, so users copying from those release tags or release notes-era files could have been misled.

• Was v1.0.0-beta-java.1 affected?
  I did not find the chained-mangling pattern in that tag. The damage appears to start with .2, then compounds in .3.

So the blast radius looks like: broken documentation/examples in the beta-java.2 and beta-java.3 releases, but not a broken published artifact version itself.