Use Maven release plugin (release:prepare and release:perform) with branch auto-detection

Copilot · thomasturrell · Copilot · commit f096dff2fc8e · 2025-11-16T16:50:09.000Z
Co-authored-by: thomasturrell &lt;1552612+thomasturrell@users.noreply.github.com&gt;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,23 +1,23 @@
 # This workflow automates the release process when a release is created on GitHub
-# It creates a release branch, updates versions, and deploys to Maven Central
+# It uses Maven release plugin to manage versions and deploys to Maven Central
 #
 # Usage:
 # 1. Create a new release in GitHub UI with tag format: vX.Y.Z (e.g., v1.2.0)
+#    - Select the target branch (typically main)
 # 2. This workflow will automatically:
-#    - Create a release-X.Y.Z branch
-#    - Update pom.xml versions to release version
-#    - Build and deploy artifacts to Maven Central
-#    - Update pom.xml to next development version
-#    - Push version commits back to the release branch
+#    - Use Maven release:prepare to update versions and create release commits
+#    - Use Maven release:perform to build and deploy artifacts to Maven Central
+#    - Move the tag to point to the actual release commit
+#    - Push commits back to the originating branch
 
 name: Automated Release
 
 on:
   release:
-    types: [created]  # Trigger when release is created (before it's published)
+    types: [created]  # Trigger when release is created
 
 permissions:
-  contents: write  # Required to create branches and push commits
+  contents: write  # Required to push commits and update tags
 
 jobs:
   release:
@@ -41,11 +41,6 @@ jobs:
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
           echo "Extracted version: $VERSION"
           
-          # Create release branch name
-          RELEASE_BRANCH="release-${VERSION}"
-          echo "release_branch=${RELEASE_BRANCH}" >> $GITHUB_OUTPUT
-          echo "Release branch: $RELEASE_BRANCH"
-          
           # Calculate next development version (increment patch version)
           IFS='.' read -ra VERSION_PARTS <<< "$VERSION"
           MAJOR="${VERSION_PARTS[0]}"
@@ -56,20 +51,36 @@ jobs:
           echo "next_version=${NEXT_VERSION}" >> $GITHUB_OUTPUT
           echo "Next development version: $NEXT_VERSION"
       
-      - name: Checkout repository at release tag
+      - name: Determine target branch
+        id: target_branch
+        run: |
+          # Use target_commitish to determine the originating branch
+          TARGET="${{ github.event.release.target_commitish }}"
+          
+          # If target_commitish is empty or a SHA, default to main
+          if [[ -z "$TARGET" ]] || [[ "$TARGET" =~ ^[0-9a-f]{40}$ ]]; then
+            TARGET="main"
+          fi
+          
+          echo "target_branch=${TARGET}" >> $GITHUB_OUTPUT
+          echo "Target branch: $TARGET"
+      
+      - name: Checkout repository
         uses: actions/checkout@v3
         with:
-          ref: ${{ github.event.release.tag_name }}
+          ref: ${{ steps.target_branch.outputs.target_branch }}
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
       
-      - name: Create release branch
+      - name: Delete user-created tag
         run: |
-          RELEASE_BRANCH="${{ steps.validate_tag.outputs.release_branch }}"
+          TAG_NAME="${{ github.event.release.tag_name }}"
+          
+          # Delete the tag created by the user (will be recreated by release:prepare)
+          git tag -d "$TAG_NAME" || true
+          git push origin ":refs/tags/$TAG_NAME" || true
           
-          # Create new branch from the release tag
-          git checkout -b "$RELEASE_BRANCH"
-          echo "Created branch $RELEASE_BRANCH from tag ${{ github.event.release.tag_name }}"
+          echo "Deleted user-created tag $TAG_NAME"
       
       - name: Set up JDK 17
         uses: actions/setup-java@v5
@@ -88,103 +99,60 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
       
-      - name: Set release version in POM
-        run: |
-          VERSION="${{ steps.validate_tag.outputs.version }}"
-          echo "Setting version to: $VERSION"
-          
-          # Use Maven versions plugin to set the version
-          ./mvnw -B versions:set -DnewVersion="${VERSION}" -DgenerateBackupPoms=false
-          
-          # Commit the version change
-          git add .
-          git commit -m "[maven-release-plugin] prepare release v${VERSION}"
-      
-      - name: Verify release build
-        run: |
-          echo "Running tests and verification for release version"
-          
-          # Build and test the release version
-          ./mvnw -B clean verify
-      
-      - name: Build and deploy release
+      - name: Run Maven release:prepare
         run: |
           VERSION="${{ steps.validate_tag.outputs.version }}"
-          echo "Building and deploying version: $VERSION"
+          NEXT_VERSION="${{ steps.validate_tag.outputs.next_version }}"
+          TAG_NAME="${{ github.event.release.tag_name }}"
           
-          # Build and deploy with release profile (includes signing, sources, javadocs)
-          ./mvnw -B clean deploy -Prelease \
-            -pl xapi-model,xapi-client,xapi-model-spring-boot-starter -am \
-            -DskipTests
+          echo "Preparing release version: $VERSION"
+          echo "Next development version: $NEXT_VERSION"
+          echo "Tag name: $TAG_NAME"
+          
+          # Run release:prepare with explicit versions
+          ./mvnw -B release:prepare \
+            -DreleaseVersion="${VERSION}" \
+            -DdevelopmentVersion="${NEXT_VERSION}" \
+            -Dtag="${TAG_NAME}" \
+            -DpushChanges=false \
+            -DremoteTagging=false
         env:
           MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
           MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
       
-      - name: Update to next development version
+      - name: Run Maven release:perform
         run: |
-          NEXT_VERSION="${{ steps.validate_tag.outputs.next_version }}"
-          echo "Setting next development version to: $NEXT_VERSION"
+          echo "Performing release and deploying to Maven Central"
           
-          # Update to next SNAPSHOT version
-          ./mvnw -B versions:set -DnewVersion="${NEXT_VERSION}" -DgenerateBackupPoms=false
-          
-          # Commit the version change
-          git add .
-          git commit -m "[maven-release-plugin] prepare for next development iteration"
+          # Run release:perform to build and deploy
+          ./mvnw -B release:perform \
+            -DlocalCheckout=true \
+            -DeployAtEnd=true
+        env:
+          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
       
-      - name: Update release tag to point to release commit
+      - name: Push changes to originating branch
         run: |
+          TARGET_BRANCH="${{ steps.target_branch.outputs.target_branch }}"
           TAG_NAME="${{ github.event.release.tag_name }}"
           
-          # Delete the existing tag locally
-          git tag -d "$TAG_NAME"
-          
-          # Get the commit hash of the release preparation commit (one before current)
-          RELEASE_COMMIT=$(git rev-parse HEAD~1)
-          
-          # Create new tag pointing to the release commit
-          git tag -a "$TAG_NAME" "$RELEASE_COMMIT" -m "Release $TAG_NAME"
-          
-          # Force push the updated tag
-          git push -f origin "$TAG_NAME"
-          
-          echo "Updated tag $TAG_NAME to point to release commit: $RELEASE_COMMIT"
-      
-      - name: Push release branch
-        run: |
-          RELEASE_BRANCH="${{ steps.validate_tag.outputs.release_branch }}"
-          
-          # Push the release branch with all commits
-          git push -u origin "$RELEASE_BRANCH"
-          
-          echo "Pushed release branch: $RELEASE_BRANCH"
-      
-      - name: Update main branch with next development version
-        run: |
-          NEXT_VERSION="${{ steps.validate_tag.outputs.next_version }}"
-          
-          echo "Updating main branch to next development version: $NEXT_VERSION"
-          
-          # Fetch and checkout main branch
-          git fetch origin main
-          git checkout main
-          
-          # Update to next SNAPSHOT version
-          ./mvnw -B versions:set -DnewVersion="${NEXT_VERSION}" -DgenerateBackupPoms=false
+          echo "Pushing changes to branch: $TARGET_BRANCH"
           
-          # Commit the version change
-          git add .
-          git commit -m "[maven-release-plugin] prepare for next development iteration"
+          # Push the commits created by release:prepare
+          git push origin "HEAD:${TARGET_BRANCH}"
           
-          # Push to main
-          git push origin main
+          # Push the tag created by release:prepare
+          git push origin "$TAG_NAME"
           
-          echo "Updated main branch to version: $NEXT_VERSION"
+          echo "Pushed release commits and tag to $TARGET_BRANCH"
       
       - name: Clean up
         if: always()
         run: |
-          # Clean up any Maven artifacts
-          rm -f release.properties
-          find . -name "pom.xml.versionsBackup" -delete || true
+          # Clean up Maven release artifacts
+          rm -f release.properties pom.xml.releaseBackup
+          find . -name "pom.xml.releaseBackup" -delete || true
+          find . -name "pom.xml.tag" -delete || true
diff --git a/RELEASING.md b/RELEASING.md
@@ -20,80 +20,85 @@ The release process is fully automated via GitHub Actions. To create a new relea
 
 1. Navigate to the [Releases page](https://github.com/BerryCloud/xapi-java/releases)
 2. Click **"Draft a new release"**
-3. Enter the tag version in the format: `vX.Y.Z` (e.g., `v1.2.0`)
+3. **Choose a tag**: Enter the tag version in the format: `vX.Y.Z` (e.g., `v1.2.0`)
    - The tag **must** start with `v` followed by semantic version numbers
    - Example: `v1.1.16`, `v2.0.0`, `v1.2.3`
-4. Enter a release title (e.g., "Release 1.2.0")
-5. Add release notes describing the changes
-6. Click **"Publish release"**
+4. **Target**: Select the branch to release from (typically `main`)
+   - The workflow will automatically detect and use this branch
+5. Enter a release title (e.g., "Release 1.2.0")
+6. Add release notes describing the changes
+7. Click **"Publish release"**
 
 ### Step 2: Automated Workflow Execution
 
 Once you publish the release, the "Automated Release" workflow will:
 
 1. ✅ Validate the tag format (must be `vX.Y.Z`)
-2. ✅ Extract the version number from the tag
-3. ✅ Create a `release-X.Y.Z` branch from the release tag
-4. ✅ Update all `pom.xml` files to the release version
-5. ✅ Commit the version change
-6. ✅ **Run full test suite** to verify the release
-7. ✅ Build and deploy artifacts to Maven Central with:
-   - Compiled JARs
-   - Source JARs
-   - Javadoc JARs
-   - GPG signatures
-8. ✅ Update the release tag to point to the release commit
-9. ✅ Update `pom.xml` files to the next SNAPSHOT version on release branch
-10. ✅ Push all commits to the release branch
-11. ✅ Update `main` branch with the next SNAPSHOT version
+2. ✅ Detect the target branch (auto-detected from release)
+3. ✅ Delete the user-created tag (will be recreated properly)
+4. ✅ **Run Maven release:prepare** to:
+   - Update all `pom.xml` files to the release version
+   - Commit the version change
+   - Create the release tag pointing to the release commit
+   - Update `pom.xml` files to the next SNAPSHOT version
+   - Commit the next development iteration
+5. ✅ **Run Maven release:perform** to:
+   - Check out the release tag
+   - Build and test the release version
+   - Deploy artifacts to Maven Central with GPG signatures
+6. ✅ Push commits and tag back to the originating branch
 
 **Workflow Diagram:**
 ```
-User Action: Create Release (tag: v1.2.0)
+User Action: Create Release (tag: v1.2.0, target: main)
     ↓
 GitHub: Creates tag v1.2.0 → commit A (from main)
     ↓
-Workflow: Checkout tag v1.2.0
+Workflow: Detects target branch (main)
     ↓
-Workflow: Create branch release-1.2.0
+Workflow: Deletes user-created tag v1.2.0
     ↓
-Workflow: Update pom.xml to 1.2.0 → commit B
+Workflow: Runs release:prepare
     ↓
-Workflow: Run tests (mvn verify)
+  - Commit B: pom.xml → 1.2.0 (release version)
+  - Creates tag v1.2.0 → commit B
+  - Commit C: pom.xml → 1.2.1-SNAPSHOT (next dev version)
     ↓
-Workflow: Build & deploy to Maven Central
+Workflow: Runs release:perform
     ↓
-Workflow: Move tag v1.2.0 to commit B
+  - Checks out tag v1.2.0 (commit B)
+  - Builds and tests
+  - Deploys to Maven Central
     ↓
-Workflow: Update pom.xml to 1.2.1-SNAPSHOT → commit C
+Workflow: Pushes commits B & C to main
     ↓
-Workflow: Push branch release-1.2.0
-    ↓
-Workflow: Update main branch → pom.xml to 1.2.1-SNAPSHOT
+Workflow: Pushes tag v1.2.0 → commit B
     ↓
 Result:
   - Tag v1.2.0 → commit B (release version)
-  - Branch release-1.2.0 → commit C (next SNAPSHOT)
-  - Main branch → updated to 1.2.1-SNAPSHOT
+  - Main branch → commit C (next SNAPSHOT: 1.2.1-SNAPSHOT)
   - Artifacts deployed to Maven Central
 ```
 
 ### Step 3: Verify Release
 
 1. Check the [Actions tab](https://github.com/BerryCloud/xapi-java/actions) to ensure the workflow completed successfully
-2. Verify the release branch was created: `release-X.Y.Z`
+2. Verify the target branch (e.g., `main`) has two new commits:
+   - Release commit: `[maven-release-plugin] prepare release vX.Y.Z`
+   - Development commit: `[maven-release-plugin] prepare for next development iteration`
 3. Verify artifacts are available on [Maven Central](https://central.sonatype.com/artifact/dev.learning.xapi/xapi-model)
 
 ## Release Branch Strategy
 
-- **Main branch (`main`)**: Contains development code with `-SNAPSHOT` versions
-  - Automatically updated to next SNAPSHOT version after each release
-- **Release branches (`release-X.Y.Z`)**: Created automatically for each release
-  - Contains two commits:
-    1. Version update to release version (X.Y.Z)
-    2. Version update to next development version (X.Y.Z+1-SNAPSHOT)
-  - The next development version commit is also applied to `main`
-- **Release tags (`vX.Y.Z`)**: Points to the release version commit
+- **Main branch (`main`)** (or other target branch): Contains development code with `-SNAPSHOT` versions
+  - After each release, receives two commits from Maven release plugin:
+    1. Release commit: Version update to release version (X.Y.Z)
+    2. Development commit: Version update to next development version (X.Y.Z+1-SNAPSHOT)
+  - The HEAD always points to the next development version
+- **Release tags (`vX.Y.Z`)**: Created by Maven release plugin
+  - Points to the release version commit (first commit)
+  - Used for reproducible builds and deployments
+- **No separate release branches**: The release workflow pushes directly to the originating branch
 
 ## Version Numbering
 
@@ -136,21 +141,34 @@ If the automated release workflow fails:
 
 4. **After fixing issues:**
    - Delete the failed release and tag in GitHub UI
-   - Delete the release branch if it was created: `git push origin --delete release-X.Y.Z`
+   - **Important**: Reset your target branch if commits were already pushed:
+     ```bash
+     # If release:prepare pushed commits before failure
+     git fetch origin
+     git checkout main  # or your target branch
+     git reset --hard origin/main~2  # Remove the 2 release commits
+     git push -f origin main
+     ```
    - Create a new release with the same tag
 
-### Release Branch Already Exists
+### Re-releasing the Same Version
 
-If you need to re-release the same version:
+If you need to re-release the same version after a failed release:
 
-1. Delete the existing release branch:
+1. Delete the existing release in GitHub UI:
+   - Go to Releases → Click on the release → Delete release
+2. Delete the tag (locally and remotely):
    ```bash
-   git push origin --delete release-X.Y.Z
+   git tag -d vX.Y.Z
+   git push origin :refs/tags/vX.Y.Z
+   ```
+3. Reset the target branch if commits were pushed:
+   ```bash
+   git fetch origin
+   git checkout main  # or your target branch
+   git reset --hard origin/main~2  # Remove the 2 release commits if they exist
+   git push -f origin main  # Only if commits were pushed
    ```
-2. Delete the existing release in GitHub UI:
-   - Go to Releases → Click on the release → Delete release
-3. Delete the tag:
-   - Go to Tags → Find the tag → Delete tag
 4. Create a new release with the same version tag
 
 ### Workflow Stuck or Taking Too Long
