Fix workflow to create separate commit and pass version explicitly

Co-authored-by: thomasturrell <1552612+thomasturrell@users.noreply.github.com>

Author: Copilot

.github/scripts/README.md

@@ -10,13 +10,16 @@ Updates version numbers in documentation examples during the release process.
 
 **Usage**:
 ```bash
-# Automatically called by .github/workflows/manual-release.yml
+# With explicit version (recommended during release)
+bash .github/scripts/update-example-versions.sh "1.2.0"
+
+# Without version argument (extracts from pom.xml)
 bash .github/scripts/update-example-versions.sh
 ```
 
 **What it does**:
-1. Extracts the current version from the root `pom.xml` (skipping parent version)
-2. Strips `-SNAPSHOT` suffix to get the release version
+1. Accepts an optional version argument (recommended to avoid confusion after release:prepare)
+2. If no argument, extracts the current version from the root `pom.xml` (skipping parent version) and strips `-SNAPSHOT` suffix
 3. Updates all `<version>` tags within `<dependency>` blocks in README.md
 4. Reports changes made via git diff
 

.github/scripts/test-update-example-versions.sh

@@ -153,10 +153,29 @@ test_snapshot_stripping() {
     fi
 }
 
-# Test 3: Full script execution in test environment
+# Test 3: Script accepts version argument
+test_version_argument() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    info "Test 3: Script accepts version argument"
+    
+    # Change to test directory to ensure we're not in repo root
+    cd "$TEST_DIR"
+    
+    # Run script with explicit version argument
+    local output=$(bash "$SCRIPT_UNDER_TEST" "9.9.9" 2>&1)
+    
+    if echo "$output" | grep -q "Using version from argument: 9.9.9"; then
+        pass "Script accepts and uses version argument"
+    else
+        fail "Version argument handling" "script should accept version argument" "script did not recognize argument"
+        echo "  Output was: $output" | head -5
+    fi
+}
+
+# Test 4: Full script execution in test environment
 test_full_script_execution() {
     TESTS_RUN=$((TESTS_RUN + 1))
-    info "Test 3: Full script execution"
+    info "Test 4: Full script execution"
 
     # Create a modified version of the script that operates in TEST_DIR
     local test_script="/tmp/test-script-$$.sh"
@@ -180,10 +199,10 @@ test_full_script_execution() {
     rm -f /tmp/test-output-$$.log "$test_script"
 }
 
-# Test 4: Version pattern matching
+# Test 5: Version pattern matching
 test_version_pattern_matching() {
     TESTS_RUN=$((TESTS_RUN + 1))
-    info "Test 4: Version pattern matching"
+    info "Test 5: Version pattern matching"
 
     # Test the sed pattern used in the script on a sample
     local sample='<dependency><version>1.0.0</version></dependency>'
@@ -197,10 +216,10 @@ test_version_pattern_matching() {
     fi
 }
 
-# Test 5: Selective replacement (only in dependency blocks)
+# Test 6: Selective replacement (only in dependency blocks)
 test_selective_replacement() {
     TESTS_RUN=$((TESTS_RUN + 1))
-    info "Test 5: Selective replacement"
+    info "Test 6: Selective replacement"
 
     # Create a test file
     cat > /tmp/test-selective-$$.md << 'EOF'
@@ -231,10 +250,10 @@ EOF
     fi
 }
 
-# Test 6: Script handles errors gracefully
+# Test 7: Script handles errors gracefully
 test_error_handling() {
     TESTS_RUN=$((TESTS_RUN + 1))
-    info "Test 6: Script handles errors gracefully"
+    info "Test 7: Script handles errors gracefully"
 
     # Test that script handles missing files gracefully
     cd "$TEST_DIR"
@@ -271,6 +290,7 @@ main() {
     # Run tests
     test_version_extraction
     test_snapshot_stripping
+    test_version_argument
     test_full_script_execution
     test_version_pattern_matching
     test_selective_replacement

.github/scripts/update-example-versions.sh

@@ -32,19 +32,27 @@ main() {
 
     echo "Updating example version numbers in documentation..."
 
-    # Get the current version from the root pom.xml
-    CURRENT_VERSION=$(get_version_from_pom "pom.xml")
-    
-    if [ -z "$CURRENT_VERSION" ]; then
-        echo "ERROR: Could not extract version from pom.xml"
-        exit 1
+    # Check if version was passed as argument
+    if [ $# -gt 0 ] && [ -n "$1" ]; then
+        # Use version from command line argument
+        RELEASE_VERSION="$1"
+        echo "Using version from argument: $RELEASE_VERSION"
+    else
+        # Get the current version from the root pom.xml
+        CURRENT_VERSION=$(get_version_from_pom "pom.xml")
+        
+        if [ -z "$CURRENT_VERSION" ]; then
+            echo "ERROR: Could not extract version from pom.xml"
+            exit 1
+        fi
+        
+        echo "Current version from pom.xml: $CURRENT_VERSION"
+        
+        # Strip -SNAPSHOT suffix if present (we want the release version)
+        RELEASE_VERSION="${CURRENT_VERSION%-SNAPSHOT}"
+        echo "Release version: $RELEASE_VERSION"
     fi
 
-    echo "Current version: $CURRENT_VERSION"
-    
-    # Strip -SNAPSHOT suffix if present (we want the release version)
-    RELEASE_VERSION="${CURRENT_VERSION%-SNAPSHOT}"
-    
     echo "Updating documentation to use version: $RELEASE_VERSION"
 
     # Files to update

.github/workflows/manual-release.yml

@@ -188,25 +188,24 @@ jobs:
         run: |
           echo "Updating example version numbers in documentation..."
           
-          # Run the script to update version numbers in README.md and other docs
-          bash .github/scripts/update-example-versions.sh
+          VERSION="${{ steps.release.outputs.version }}"
+          
+          # Run the script with the explicit release version
+          # Pass version directly to avoid reading from pom.xml which now has SNAPSHOT
+          bash .github/scripts/update-example-versions.sh "$VERSION"
           
           # Check if there are any changes
           if git diff --quiet; then
             echo "No version updates needed"
           else
-            echo "Documentation examples updated with release version"
+            echo "Documentation examples updated with release version $VERSION"
             
-            # Amend the release commit created by release:prepare to include doc updates
-            # Only add README.md since that's what the script updates
+            # Create a third commit for documentation updates
+            # This is safer than amending either of the release:prepare commits
             git add README.md
-            git commit --amend --no-edit
-            
-            # Update the tag to point to the amended commit
-            TAG_NAME="${{ steps.release.outputs.tag_name }}"
-            git tag -f "$TAG_NAME"
+            git commit -m "[release] Update documentation examples to version $VERSION"
             
-            echo "✅ Release commit amended with documentation updates"
+            echo "✅ Documentation updated in separate commit"
           fi
       
       - name: Run Maven release:perform

RELEASING.md

@@ -53,8 +53,7 @@ Once you trigger the workflow, the "Manual Draft Release" workflow will:
    - Commit the next development iteration
 5. ✅ **Update example version numbers in documentation**:
    - Automatically update version numbers in README.md dependency examples
-   - Amend the release commit to include documentation updates
-   - Update the tag to point to the amended commit
+   - Create a third commit with the documentation updates
    - Ensures documentation examples always match the release version
 6. ✅ **Run Maven release:perform** to:
    - Check out the release tag
@@ -89,16 +88,15 @@ Workflow: Runs release:prepare on main branch
 Workflow: Updates example versions in documentation
     ↓
   - Updates README.md with version 1.2.0
-  - Amends Commit A to include documentation updates
-  - Updates tag v1.2.0 → amended Commit A
+  - Commit C: Documentation updates
     ↓
 Workflow: Runs release:perform
     ↓
   - Checks out tag v1.2.0 (commit A)
   - Builds and tests
   - Deploys to Maven Central
     ↓
-Workflow: Pushes commits A & B to main
+Workflow: Pushes commits A, B & C to main
     ↓
 Workflow: Pushes tag v1.2.0 → commit A
     ↓
@@ -108,7 +106,7 @@ Workflow: Publishes the GitHub Release
     ↓
 Result:
   - Tag v1.2.0 → commit A (release version: 1.2.0)
-  - Main branch → commit B (next SNAPSHOT: 1.2.1-SNAPSHOT)
+  - Main branch → commit C (next SNAPSHOT: 1.2.1-SNAPSHOT, with updated docs)
   - Artifacts deployed to Maven Central
   - GitHub Release published with JAR files
 ```
@@ -117,9 +115,10 @@ Result:
 
 1. Check the [Actions tab](https://github.com/BerryCloud/xapi-java/actions) to ensure the workflow completed successfully
    - The workflow will show a summary of the release including version, tag, and status
-2. Verify the target branch (e.g., `main`) has two new commits:
-   - Release commit: `[maven-release-plugin] prepare release vX.Y.Z` (amended to include documentation updates)
+2. Verify the target branch (e.g., `main`) has three new commits:
+   - Release commit: `[maven-release-plugin] prepare release vX.Y.Z`
    - Development commit: `[maven-release-plugin] prepare for next development iteration`
+   - Documentation commit: `[release] Update documentation examples to version X.Y.Z`
 3. Verify the GitHub Release was published at the [Releases page](https://github.com/BerryCloud/xapi-java/releases)
    - The release should no longer be in draft state
    - JAR artifacts should be attached to the release