feat: enhance release process to track upstream SDK sync in CHANGELOG and update scripts

Author: brunoborges

.github/copilot-instructions.md

@@ -258,14 +258,20 @@ The release process is automated via the `publish-maven.yml` GitHub Actions work
    - Converts the `## [Unreleased]` section to `## [version] - date`
    - Creates a new empty `## [Unreleased]` section at the top
    - Updates version comparison links at the bottom of CHANGELOG.md
+   - Injects the upstream SDK commit hash (from `.lastmerge`) as a `> **Upstream sync:**` blockquote in both the new `[Unreleased]` section and the released version section
 
-2. **Documentation Updates**: README.md and jbang-example.java are updated with the new version
+2. **Upstream Sync Tracking**: Each release records which commit from the official `github/copilot-sdk` it is synced to:
+   - The `.lastmerge` file is read during the release workflow
+   - The commit hash is injected into `CHANGELOG.md` under the release heading
+   - Format: `> **Upstream sync:** [\`github/copilot-sdk@SHORT_HASH\`](link-to-commit)`
 
-3. **Maven Release**: Uses `maven-release-plugin` to:
+3. **Documentation Updates**: README.md and jbang-example.java are updated with the new version.
+
+4. **Maven Release**: Uses `maven-release-plugin` to:
    - Update pom.xml version
    - Create a git tag
    - Deploy to Maven Central
 
-4. **Rollback**: If the release fails, the documentation commit is automatically reverted
+5. **Rollback**: If the release fails, the documentation commit is automatically reverted
 
 The workflow is triggered manually via workflow_dispatch with optional version parameters.

.github/scripts/update-changelog.sh

@@ -2,20 +2,25 @@
 set -e
 
 # Script to update CHANGELOG.md during release process
-# Usage: ./update-changelog.sh <version>
+# Usage: ./update-changelog.sh <version> [upstream-hash]
 # Example: ./update-changelog.sh 1.0.8
+# Example: ./update-changelog.sh 1.0.8 05e3c46c8c23130c9c064dc43d00ec78f7a75eab
 
 if [ -z "$1" ]; then
     echo "Error: Version argument required"
-    echo "Usage: $0 <version>"
+    echo "Usage: $0 <version> [upstream-hash]"
     exit 1
 fi
 
 VERSION="$1"
+UPSTREAM_HASH="${2:-}"
 CHANGELOG_FILE="${CHANGELOG_FILE:-CHANGELOG.md}"
 RELEASE_DATE=$(date +%Y-%m-%d)
 
 echo "Updating CHANGELOG.md for version ${VERSION} (${RELEASE_DATE})"
+if [ -n "$UPSTREAM_HASH" ]; then
+    echo "  Upstream SDK sync: ${UPSTREAM_HASH:0:7}"
+fi
 
 # Check if CHANGELOG.md exists
 if [ ! -f "$CHANGELOG_FILE" ]; then
@@ -33,7 +38,7 @@ fi
 TEMP_FILE=$(mktemp)
 
 # Process the CHANGELOG
-awk -v version="$VERSION" -v date="$RELEASE_DATE" '
+awk -v version="$VERSION" -v date="$RELEASE_DATE" -v upstream_hash="$UPSTREAM_HASH" '
 BEGIN {
     unreleased_found = 0
     content_found = 0
@@ -60,12 +65,27 @@ links_section && repo_url == "" && /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/ {
     if (!unreleased_found) {
         print "## [Unreleased]"
         print ""
+        if (upstream_hash != "") {
+            short_hash = substr(upstream_hash, 1, 7)
+            print "> **Upstream sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" upstream_hash ")"
+            print ""
+        }
         print "## [" version "] - " date
+        if (upstream_hash != "") {
+            print ""
+            print "> **Upstream sync:** [`github/copilot-sdk@" short_hash "`](https://github.com/github/copilot-sdk/commit/" upstream_hash ")"
+        }
         unreleased_found = 1
+        skip_old_upstream = 1
         next
     }
 }
 
+# Skip the old upstream sync line and surrounding blank lines from the previous [Unreleased] section
+skip_old_upstream && /^[[:space:]]*$/ { next }
+skip_old_upstream && /^> \*\*Upstream sync:\*\*/ { next }
+skip_old_upstream && !/^[[:space:]]*$/ && !/^> \*\*Upstream sync:\*\*/ { skip_old_upstream = 0 }
+
 # Capture the first version link to get the previous version
 links_section && first_version_link == "" && /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/ {
     match($0, /\[([0-9]+\.[0-9]+\.[0-9]+)\]:/, arr)

.github/workflows/publish-maven.yml

@@ -100,8 +100,14 @@ jobs:
               run: |
                   VERSION="${{ steps.versions.outputs.release_version }}"
                   
-                  # Update CHANGELOG.md with release version
-                  ./.github/scripts/update-changelog.sh "${VERSION}"
+                  # Read the upstream SDK commit hash that this release is synced to
+                  UPSTREAM_HASH=$(cat .lastmerge)
+                  UPSTREAM_SHORT="${UPSTREAM_HASH:0:7}"
+                  UPSTREAM_URL="https://github.com/github/copilot-sdk/commit/${UPSTREAM_HASH}"
+                  echo "Upstream SDK sync: ${UPSTREAM_SHORT} (${UPSTREAM_URL})"
+                  
+                  # Update CHANGELOG.md with release version and upstream sync hash
+                  ./.github/scripts/update-changelog.sh "${VERSION}" "${UPSTREAM_HASH}"
                   
                   # Update version in README.md
                   sed -i "s|<version>[0-9]*\.[0-9]*\.[0-9]*</version>|<version>${VERSION}</version>|g" README.md

CHANGELOG.md

@@ -2,13 +2,18 @@
 
 All notable changes to the Copilot SDK for Java will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> Note: This file is automatically modified by scripts and coding agents. Do not change it manually.
 
 ## [Unreleased]
 
+> **Upstream sync:** [`github/copilot-sdk@05e3c46`](https://github.com/github/copilot-sdk/commit/05e3c46c8c23130c9c064dc43d00ec78f7a75eab)
+
 ## [1.0.8] - 2026-02-08
 
+> **Upstream sync:** [`github/copilot-sdk@05e3c46`](https://github.com/github/copilot-sdk/commit/05e3c46c8c23130c9c064dc43d00ec78f7a75eab)
+
 ### Added
 
 #### ResumeSessionConfig Parity with SessionConfig