fix: improve hotfix flow (#2523)

Author: brojd

.github/workflows/on-pull-requests.yml

@@ -85,61 +85,6 @@ jobs:
           echo "::error::❄️ Release freeze is active. Merging release-please PRs is blocked."
           exit 1
 
-  version-clash-check:
-    name: Version Clash Check
-    # Only run on release-please PRs
-    if: github.event_name == 'pull_request' && startsWith(github.head_ref, 'release-please--')
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - name: Extract version from PR title
-        id: extract-version
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-        run: |
-          # PR title format: "chore(main): release platform vX.Y.Z" or "chore(release/vX.Y.Z): release platform vX.Y.Z"
-          VERSION=$(echo "$PR_TITLE" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | tail -1)
-          if [ -z "$VERSION" ]; then
-            echo "⚠️ Could not extract version from PR title: $PR_TITLE"
-            echo "version=" >> "$GITHUB_OUTPUT"
-          else
-            echo "📦 Extracted version: $VERSION"
-            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Check if version tag already exists
-        if: steps.extract-version.outputs.version != ''
-        env:
-          VERSION: ${{ steps.extract-version.outputs.version }}
-          BASE_REF: ${{ github.base_ref }}
-        run: |
-          # Check if the tag already exists
-          if git rev-parse "platform-$VERSION" >/dev/null 2>&1; then
-            echo "::error::❌ Version clash detected! Tag 'platform-$VERSION' already exists."
-            echo ""
-            echo "This usually happens when a hotfix release was created while this PR was open."
-            echo ""
-            echo "To fix this, bump the version on your target branch:"
-            echo ""
-            echo "  git checkout $BASE_REF"
-            echo "  git pull"
-            echo "  git commit -m \"chore(release): bump version\" -m \"release-as: X.Y.Z\" --allow-empty"
-            echo "  git push"
-            echo ""
-            echo "Replace X.Y.Z with the next available version number."
-            echo "See RELEASE.md for more details on handling version clashes."
-            exit 1
-          else
-            echo "✅ No version clash - tag 'platform-$VERSION' does not exist yet"
-          fi
-
   lint-pr-title:
     name: PR Title Linter
     if: github.event_name == 'pull_request'

platform/dev/RELEASE.md

@@ -81,8 +81,6 @@ When you merge to `release/v1.0.22`:
 - Release Please creates a PR for `v1.0.23` targeting the release branch
 - Merge this PR to create the hotfix release
 
-**Important:** If there's already a release-please PR on `main` targeting the same version (v1.0.23), you'll need to resolve the version clash after releasing the hotfix. See [Version Clash](#version-clash-after-hotfix) in Troubleshooting.
-
 ### 4. Backport to Main
 
 After releasing the hotfix, apply the fix to `main`:
@@ -99,6 +97,19 @@ git cherry-pick <commit-sha>
 git push origin main
 ```
 
+### 5. IMPORTANT! Bump the version on `main` using the `release-as` directive:
+
+```bash
+git checkout main
+git pull origin main
+git commit -m "chore(release): bump version" -m "release-as: X.Y.Z" --allow-empty
+git push origin main
+```
+(alternatively create PR with this empty commit and merge to `main`)
+Replace X.Y.Z with a version higher than the hotfix you just released (e.g., if hotfix was v1.0.23, use v1.0.24)
+
+Now the version of existing release-please PR for `main` will be bumped
+
 ## Quick Reference
 
 ### Release a New Version
@@ -145,22 +156,3 @@ Check the "On commits to main" workflow for errors. Common issues:
 - Docker build failures
 - Kubernetes deployment issues
 - Secret configuration problems
-
-### Version Clash After Hotfix
-
-**Scenario:** You released a hotfix (e.g., v1.0.23) from a `release/*` branch, but `main` already has a release-please PR targeting the same version.
-
-**Symptom:** The "Version Clash Check" CI job fails on the release-please PR for `main`.
-
-**Solution:** Bump the version on `main` using the `release-as` directive:
-
-```bash
-git checkout main
-git pull origin main
-git commit -m "chore(release): bump version" -m "release-as: 1.0.24" --allow-empty
-git push origin main
-```
-
-This creates an empty commit that tells Release Please to target v1.0.24 instead. The release-please PR will automatically update.
-
-**Prevention:** Before merging any release-please PR, check that the target version hasn't already been used. The CI check does this automatically, but if you're releasing a hotfix, be aware that you may need to bump the version on `main` afterwards.