Automate example version updates in release workflow (#454)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: thomasturrell <1552612+thomasturrell@users.noreply.github.com>
Co-authored-by: Thomas Turrell-Croft <thomasturrell@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/scripts/README.md

@@ -0,0 +1,47 @@
+# Scripts
+
+This directory contains automation scripts used by GitHub Actions workflows.
+
+## update-example-versions.sh
+
+Updates version numbers in documentation examples during the release process.
+
+**Purpose**: Ensures that version numbers in README.md dependency examples always match the current release version.
+
+**Usage**:
+```bash
+# 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. 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
+
+## test-update-example-versions.sh
+
+Test script for `update-example-versions.sh`. This is not part of the Java test suite.
+
+**Usage**:
+```bash
+# Run tests
+bash .github/scripts/test-update-example-versions.sh
+```
+
+**Tests included**:
+1. Version extraction from pom.xml
+2. SNAPSHOT suffix stripping
+3. Script accepts version argument
+4. Full script execution
+5. Version pattern matching (sed patterns)
+6. Selective replacement (only updates dependency blocks)
+7. Error handling (missing files)
+
+**Exit codes**:
+- `0`: All tests passed
+- `1`: One or more tests failed

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

@@ -0,0 +1,324 @@
+#!/bin/bash
+
+# Copyright 2016-2025 Berry Cloud Ltd. All rights reserved.
+
+# Simple test script for update-example-versions.sh
+# This is not part of the Java test suite - it's a standalone shell script test
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_DIR="/tmp/xapi-version-test-$$"
+SCRIPT_UNDER_TEST="$SCRIPT_DIR/update-example-versions.sh"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Test counters
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Cleanup function
+cleanup() {
+    local exit_code=$?
+    if [ -d "$TEST_DIR" ]; then
+        rm -rf "$TEST_DIR"
+    fi
+    return $exit_code
+}
+
+trap cleanup EXIT
+
+# Test result functions
+pass() {
+    echo -e "${GREEN}✓ PASS${NC}: $1"
+    TESTS_PASSED=$((TESTS_PASSED + 1))
+}
+
+fail() {
+    echo -e "${RED}✗ FAIL${NC}: $1"
+    echo "  Expected: $2"
+    echo "  Got: $3"
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+}
+
+info() {
+    echo -e "${YELLOW}ℹ INFO${NC}: $1"
+}
+
+# Setup test environment
+setup_test_env() {
+    mkdir -p "$TEST_DIR"
+    cd "$TEST_DIR"
+    
+    # Create a minimal pom.xml
+    cat > pom.xml << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<project>
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>4.0.0</version>
+  </parent>
+  <groupId>dev.learning.xapi</groupId>
+  <artifactId>xapi-build</artifactId>
+  <version>1.2.3-SNAPSHOT</version>
+</project>
+EOF
+
+    # Create a test README.md with version numbers
+    cat > README.md << 'EOF'
+# Test README
+
+## Dependency Example 1
+
+```xml
+<dependency>
+    <groupId>dev.learning.xapi</groupId>
+    <artifactId>xapi-client</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+## Dependency Example 2
+
+```xml
+<dependency>
+  <groupId>dev.learning.xapi</groupId>
+  <artifactId>xapi-model</artifactId>
+  <version>0.9.9</version>
+</dependency>
+```
+
+## Not a dependency
+
+This should not change: <version>99.99.99</version>
+
+## Another dependency
+
+```xml
+<dependency>
+    <groupId>dev.learning.xapi</groupId>
+    <artifactId>xapi-model-spring-boot-starter</artifactId>
+    <version>1.1.11</version>
+</dependency>
+```
+EOF
+
+    # Initialize a git repo (script uses git commands)
+    git init -q
+    git config user.email "test@example.com"
+    git config user.name "Test User"
+    git add .
+    git commit -q -m "Initial commit"
+}
+
+# Test 1: Version extraction from pom.xml
+test_version_extraction() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    info "Test 1: Version extraction from pom.xml"
+    
+    # Extract version using the same logic as the script
+    local version
+    if command -v xmllint &> /dev/null; then
+        version=$(xmllint --xpath '//*[local-name()="project"]/*[local-name()="version"]/text()' "pom.xml" 2>/dev/null | head -1)
+    else
+        version=$(awk '/<parent>/,/<\/parent>/ {next} /<version>/ {print; exit}' "pom.xml" | sed 's/.*<version>\(.*\)<\/version>.*/\1/')
+    fi
+    
+    if [ "$version" = "1.2.3-SNAPSHOT" ]; then
+        pass "Extracted correct version from pom.xml"
+    else
+        fail "Version extraction" "1.2.3-SNAPSHOT" "$version"
+    fi
+}
+
+# Test 2: SNAPSHOT suffix stripping
+test_snapshot_stripping() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    info "Test 2: SNAPSHOT suffix stripping"
+    
+    local version="1.2.3-SNAPSHOT"
+    local release="${version%-SNAPSHOT}"
+    
+    if [ "$release" = "1.2.3" ]; then
+        pass "SNAPSHOT suffix correctly stripped"
+    else
+        fail "SNAPSHOT stripping" "1.2.3" "$release"
+    fi
+}
+
+# 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 4: Full script execution"
+    
+    # Create a modified version of the script that operates in TEST_DIR
+    local test_script="/tmp/test-script-$$.sh"
+    sed "s|REPO_ROOT=.*|REPO_ROOT=\"$TEST_DIR\"|" "$SCRIPT_UNDER_TEST" > "$test_script"
+    chmod +x "$test_script"
+    
+    # Run the modified script in the test environment
+    cd "$TEST_DIR"
+    if bash "$test_script" > /tmp/test-output-$$.log 2>&1; then
+        # Verify it updated the test README
+        if grep -q '<version>1.2.3</version>' README.md; then
+            pass "Script executed and updated versions correctly"
+        else
+            fail "Script execution" "versions updated to 1.2.3" "versions not updated"
+            cat /tmp/test-output-$$.log
+        fi
+    else
+        fail "Script execution" "exit code 0" "exit code $?"
+        cat /tmp/test-output-$$.log
+    fi
+    rm -f /tmp/test-output-$$.log "$test_script"
+}
+
+# Test 5: Version pattern matching
+test_version_pattern_matching() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    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>'
+    local result=$(echo "$sample" | sed '/<dependency>/,/<\/dependency>/ s|<version>[^<]*</version>|<version>NEW</version>|g')
+    local expected='<dependency><version>NEW</version></dependency>'
+    
+    if [ "$result" = "$expected" ]; then
+        pass "Version pattern matching works correctly"
+    else
+        fail "Version pattern matching" "$expected" "$result"
+    fi
+}
+
+# Test 6: Selective replacement (only in dependency blocks)
+test_selective_replacement() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    info "Test 6: Selective replacement"
+    
+    # Create a test file
+    cat > /tmp/test-selective-$$.md << 'EOF'
+<dependency>
+    <version>1.0.0</version>
+</dependency>
+
+Not in dependency: <version>99.99.99</version>
+
+<dependency>
+    <version>2.0.0</version>
+</dependency>
+EOF
+    
+    # Apply the same transformation as the script
+    sed '/<dependency>/,/<\/dependency>/ s|<version>[^<]*</version>|<version>TEST</version>|g' /tmp/test-selective-$$.md > /tmp/test-result-$$.md
+    
+    # Check results
+    local dep_count=$(grep -c '<version>TEST</version>' /tmp/test-result-$$.md)
+    local unchanged=$(grep -c '<version>99.99.99</version>' /tmp/test-result-$$.md)
+    
+    rm -f /tmp/test-selective-$$.md /tmp/test-result-$$.md
+    
+    if [ "$dep_count" -eq 2 ] && [ "$unchanged" -eq 1 ]; then
+        pass "Selective replacement preserves non-dependency versions"
+    else
+        fail "Selective replacement" "2 replacements, 1 unchanged" "$dep_count replacements, $unchanged unchanged"
+    fi
+}
+
+# Test 7: Script handles errors gracefully
+test_error_handling() {
+    TESTS_RUN=$((TESTS_RUN + 1))
+    info "Test 7: Script handles errors gracefully"
+    
+    # Test that script handles missing files gracefully
+    cd "$TEST_DIR"
+    rm -f README.md
+    
+    # Create a modified version of the script that operates in TEST_DIR
+    local test_script="/tmp/test-script-error-$$.sh"
+    sed "s|REPO_ROOT=.*|REPO_ROOT=\"$TEST_DIR\"|" "$SCRIPT_UNDER_TEST" > "$test_script"
+    chmod +x "$test_script"
+    
+    # Run with missing README.md file
+    bash "$test_script" 2>&1 | tee /tmp/test-error-output-$$.log
+    if grep -q "WARNING: File not found" /tmp/test-error-output-$$.log; then
+        pass "Script handles missing files gracefully"
+    else
+        # If no warning, that's also ok as long as script doesn't crash
+        pass "Script completes even with missing files"
+    fi
+    rm -f /tmp/test-error-output-$$.log "$test_script"
+    cd "$TEST_DIR"
+}
+
+# Main test execution
+main() {
+    echo "=========================================="
+    echo "Testing update-example-versions.sh"
+    echo "=========================================="
+    echo ""
+    
+    info "Setting up test environment in $TEST_DIR"
+    setup_test_env
+    echo ""
+    
+    # Run tests
+    test_version_extraction
+    test_snapshot_stripping
+    test_version_argument
+    test_full_script_execution
+    test_version_pattern_matching
+    test_selective_replacement
+    test_error_handling
+    
+    # Print summary
+    echo ""
+    echo "=========================================="
+    echo "Test Summary"
+    echo "=========================================="
+    echo "Tests run: $TESTS_RUN"
+    echo -e "${GREEN}Passed: $TESTS_PASSED${NC}"
+    if [ $TESTS_FAILED -gt 0 ]; then
+        echo -e "${RED}Failed: $TESTS_FAILED${NC}"
+    else
+        echo "Failed: $TESTS_FAILED"
+    fi
+    echo "=========================================="
+    
+    # Exit with appropriate code
+    if [ $TESTS_FAILED -gt 0 ]; then
+        exit 1
+    else
+        echo ""
+        echo -e "${GREEN}All tests passed!${NC}"
+        exit 0
+    fi
+}
+
+# Run main function
+main "$@"