Automate example version updates in release workflow

[Copilot]

Description

Manual version updates in documentation examples are error-prone and frequently forgotten. This PR automates version number updates during the release process.

Changes

Script (.github/scripts/update-example-versions.sh):

• Accepts version as command-line argument (recommended to avoid reading wrong version from pom.xml)
• Falls back to extracting version from root pom.xml (skipping parent pom) if no argument provided
• Updates all <version> tags within <dependency> blocks in README.md
• Cross-platform sed syntax with explicit temp files

Test Script (.github/scripts/test-update-example-versions.sh):

• Standalone bash test script (not part of Java test suite)
• Validates version extraction, pattern matching, selective replacement, and version argument handling
• 7 comprehensive tests covering all script functionality
• Run with: bash .github/scripts/test-update-example-versions.sh

Workflow (.github/workflows/manual-release.yml):

• New step after release:prepare runs the update script with explicit version argument
• Creates a third commit for documentation changes (safer than amending)
• Does not modify the release tag or either of Maven's commits

Documentation (RELEASING.md and .github/scripts/README.md):

• Added automation overview section
• Updated workflow diagram to show 3-commit workflow
• Added verification steps for documentation updates
• Documented script usage and test procedures

Behavior

During release, the script transforms:

<dependency>
    <groupId>dev.learning.xapi</groupId>
    <artifactId>xapi-client</artifactId>
    <version>1.1.11</version>  <!-- old -->
</dependency>

To:

<dependency>
    <groupId>dev.learning.xapi</groupId>
    <artifactId>xapi-client</artifactId>
    <version>1.2.0</version>  <!-- matches release -->
</dependency>

Workflow Sequence

After Maven's release:prepare creates two commits:

1. Commit A (release): pom.xml → 1.2.0
2. Commit B (development): pom.xml → 1.2.1-SNAPSHOT

The automation creates:
3. Commit C (documentation): README.md → version 1.2.0

The release tag (v1.2.0) points to Commit A. The main branch ends at Commit C with updated documentation.

Critical Fix: The script receives version 1.2.0 as an explicit argument, avoiding the issue where reading from pom.xml after release:prepare would get 1.2.1-SNAPSHOT and incorrectly use 1.2.1 (the next release) instead of 1.2.0 (the current release).

Testing

The test script validates:

1. ✅ Version extraction from pom.xml
2. ✅ SNAPSHOT suffix stripping
3. ✅ Script accepts version argument (NEW)
4. ✅ Full script execution without errors
5. ✅ Version pattern matching (sed patterns work correctly)
6. ✅ Selective replacement (only updates dependency blocks, preserves other versions)
7. ✅ Error handling (gracefully handles missing files)

All 7 tests pass successfully.

Checklist:

• Public methods are documented
• Public methods are tested
• New and existing tests pass when run locally
• There are no new warnings or errors

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Chore]: Automate updating example version numbers during release</issue_title>
<issue_description>### What

Automate updating example version numbers in documentation and code examples to always reflect the latest version during the prepare release step in the release workflow. Solutions to consider:

• Programmatically retrieve the latest version, e.g., from Maven/Gradle.
• Use a find-and-replace approach in key example files as part of CI/CD.
• Consider using scripting (e.g., shell, Python) within GitHub Actions to update all example version numbers.
• Evaluate more sophisticated tools that parse and rewrite example code blocks if needed.
  Evaluation criteria:
• Reliability/robustness as workflow changes
• Minimizing false positives or missed updates
• Ease of maintenance
• Transparency of changes in PRs

Why

Manual updates of example version numbers are error-prone and often forgotten, leading to confusion for users who copy-paste outdated examples. Automating this step as part of the release workflow aligns examples with the latest release and improves user experience and documentation quality.

Notes

Potential implementation: Add a CI step that runs after the version bump—uses a script to find and replace old version numbers in README.md, docs, and example source files. Explore using regular expressions for flexibility, but validate that only targeted examples are changed. Document the new step for contributors. Optionally review available GitHub Action/pipeline utilities that specialize in this type of chore.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Chore]: Automate updating example version numbers during release #453

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[thomasturrell]

@copilot can release:prepare be given additional tasks to perform?

[Copilot]

@copilot can release:prepare be given additional tasks to perform?

Yes, release:prepare can be configured with additional Maven goals via the preparationGoals or completionGoals configuration parameters. However, for this use case, the current approach (separate script + commit amendment) is better because:

1. Not a Maven task: Updating documentation isn't a Maven goal - it's a bash script that operates on markdown files
2. Simpler maintenance: The script is standalone and doesn't require Maven plugin wrapping
3. Flexibility: Can easily extend to non-Maven files or projects
4. Clear separation: Maven handles versioning, script handles docs

To integrate it into release:prepare, you'd need to:

• Wrap the script in a custom Maven plugin or use maven-exec-plugin
• Configure it in preparationGoals (runs before commit) or completionGoals (runs after)
• Handle the complexity of Maven's forked execution context

The current workflow approach is cleaner for this scenario.

[thomasturrell]

@copilot is it possible to have a simple test for the script? It shouldn't need to be part of the java test suite

[Copilot]

@copilot is it possible to have a simple test for the script? It shouldn't need to be part of the java test suite

Added a standalone test script at .github/scripts/test-update-example-versions.sh. It's not part of the Java test suite - it's a simple bash script that validates:

1. Version extraction from pom.xml
2. SNAPSHOT suffix stripping
3. Script execution without errors
4. Version pattern matching (sed patterns)
5. Selective replacement (only dependency blocks)
6. Error handling

Run with: bash .github/scripts/test-update-example-versions.sh

All 6 tests pass ✓ (commits 0e61213 and b6d2d0d)

[Copilot]

Pull request overview

This PR automates version number updates in documentation examples during the Maven release process. The automation aims to ensure that code examples in README.md always reflect the current release version, eliminating manual update errors. However, there is a critical issue with the git commit amendment logic that needs to be addressed before merging.

Key Changes:

• Adds a bash script to extract version from pom.xml and update dependency examples in README.md
• Integrates the script into the manual release workflow between release:prepare and release:perform
• Provides comprehensive bash-based tests for the update script
• Documents the automation in RELEASING.md and adds script documentation

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.github/scripts/update-example-versions.sh	Main automation script that extracts version from pom.xml and updates <version> tags within <dependency> blocks in README.md
.github/scripts/test-update-example-versions.sh	Standalone bash test suite with 6 tests validating version extraction, pattern matching, and error handling
.github/workflows/manual-release.yml	Integrates the version update script after release:prepare with git commit amendment to include documentation updates
RELEASING.md	Documents the automated version update process, workflow changes, and verification steps
.github/scripts/README.md	Provides usage documentation and test instructions for the automation scripts

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud