enh(DX-6154): adopt development→main release flow, back-merge, and version checks

.github/workflows/back-merge-pr.yml

@@ -0,0 +1,59 @@
+# Opens a PR from master → development after changes land on master (back-merge).
+#
+# Org/repo Settings → Actions → General → Workflow permissions: read and write
+# (so GITHUB_TOKEN can create pull requests). Or use a PAT in secret GH_TOKEN.
+
+name: Back-merge master to development
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-back-merge-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Open back-merge PR if needed
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git fetch origin development master
+
+          MASTER_SHA=$(git rev-parse origin/master)
+          DEV_SHA=$(git rev-parse origin/development)
+
+          if [ "$MASTER_SHA" = "$DEV_SHA" ]; then
+            echo "master and development are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --state open \
+            --json number \
+            --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from master to development already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}" \
+            --base development \
+            --head master \
+            --title "chore: back-merge master into development" \
+            --body "Automated back-merge after changes landed on \`master\`. Review and merge to keep \`development\` in sync."
+
+          echo "Created back-merge PR master → development."

.github/workflows/check-version-bump.yml

@@ -0,0 +1,111 @@
+# Release-affecting changes under src/main/ or pom.xml require pom.xml + changelog.md bumps
+# aligned with the latest tag. Skips when only tests, .github, skills, or docs change.
+
+name: Check Version Bump
+
+on:
+  pull_request:
+
+jobs:
+  version-bump:
+    name: Version & changelog bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed files
+        id: detect
+        run: |
+          FILES=$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")
+          echo "Changed files:"
+          echo "$FILES"
+
+          CODE_CHANGED=false
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            if [[ "$f" == src/main/* ]] || [[ "$f" == "pom.xml" ]]; then
+              CODE_CHANGED=true
+              break
+            fi
+          done <<< "$FILES"
+
+          POM_CHANGED=false
+          CHANGELOG_CHANGED=false
+          echo "$FILES" | grep -qx 'pom.xml' && POM_CHANGED=true
+          echo "$FILES" | grep -qx 'changelog.md' && CHANGELOG_CHANGED=true
+
+          VERSION_FILES_OK=false
+          if [ "$POM_CHANGED" = true ] && [ "$CHANGELOG_CHANGED" = true ]; then
+            VERSION_FILES_OK=true
+          fi
+
+          echo "code_changed=$CODE_CHANGED" >> "$GITHUB_OUTPUT"
+          echo "version_files_ok=$VERSION_FILES_OK" >> "$GITHUB_OUTPUT"
+
+      - name: Skip when no release-affecting code changed
+        if: steps.detect.outputs.code_changed != 'true'
+        run: |
+          echo "No src/main or pom-only release path triggered (e.g. tests/docs/.github only). Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version bump files were not both updated
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_ok != 'true'
+        run: |
+          echo "::error::This PR changes release-affecting code but pom.xml and/or changelog.md were not both updated. Bump <version> in pom.xml and add a ## vX.Y.Z section in changelog.md."
+          exit 1
+
+      - name: Validate version vs latest tag and changelog header
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_ok == 'true'
+        run: |
+          set -euo pipefail
+          POM_VERSION=$(python3 <<'PY'
+          import xml.etree.ElementTree as ET
+          root = ET.parse("pom.xml").getroot()
+          ns = {"m": "http://maven.apache.org/POM/4.0.0"}
+          el = root.find("m:version", ns)
+          if el is None or not (el.text or "").strip():
+              raise SystemExit("Could not read project version from pom.xml")
+          print(el.text.strip())
+          PY
+          )
+
+          git fetch --tags --force 2>/dev/null || true
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || true)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found. Skipping semver vs tag check (first release)."
+            CHANGELOG_HEAD=$(sed -nE 's/^## v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' changelog.md | head -1)
+            if [ -z "$CHANGELOG_HEAD" ]; then
+              echo "::error::Could not find a ## vX.Y.Z entry at the top of changelog.md."
+              exit 1
+            fi
+            if [ "$CHANGELOG_HEAD" != "$POM_VERSION" ]; then
+              echo "::error::changelog.md top version ($CHANGELOG_HEAD) does not match pom.xml version ($POM_VERSION)."
+              exit 1
+            fi
+            exit 0
+          fi
+
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$POM_VERSION" | sort -V | tail -1)" != "$POM_VERSION" ]; then
+            echo "::error::pom.xml version ($POM_VERSION) must be greater than latest tag ($LATEST_TAG)."
+            exit 1
+          fi
+          if [ "$POM_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::pom.xml version ($POM_VERSION) must be strictly greater than latest tag version ($LATEST_VERSION)."
+            exit 1
+          fi
+
+          CHANGELOG_HEAD=$(sed -nE 's/^## v?([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' changelog.md | head -1)
+          if [ -z "$CHANGELOG_HEAD" ]; then
+            echo "::error::Could not find a ## vX.Y.Z entry at the top of changelog.md."
+            exit 1
+          fi
+          if [ "$CHANGELOG_HEAD" != "$POM_VERSION" ]; then
+            echo "::error::changelog.md top version ($CHANGELOG_HEAD) does not match pom.xml version ($POM_VERSION)."
+            exit 1
+          fi
+          echo "Version bump check passed: pom.xml and changelog.md at $POM_VERSION (latest tag: $LATEST_TAG)."

.github/workflows/maven-publish.yml

@@ -1,9 +1,11 @@
 name: Publish package to the Maven Central Repository
 
+# Publishes when a GitHub Release is created (same pattern as before tag-based experiments).
 on:
   release:
     types:
       - created
+
 jobs:
   publish-maven:
     runs-on: ubuntu-latest

skills/README.md

@@ -6,7 +6,7 @@ Source of truth for detailed guidance. Read [AGENTS.md](../AGENTS.md) first, the
 
 | Skill folder | Use when |
 | --- | --- |
-| [dev-workflow](dev-workflow/SKILL.md) | Branching against `master`/`staging`, running Maven/CI commands, release or publish touchpoints. |
+| [dev-workflow](dev-workflow/SKILL.md) | Branching (`development` → `master`, back-merge, GitHub Release publish), Maven/CI, publish touchpoints. |
 | [contentstack-java-cma-sdk](contentstack-java-cma-sdk/SKILL.md) | Changing public API, `Contentstack` / `Stack` flows, auth tokens, or SDK surface exposed to integrators. |
 | [java](java/SKILL.md) | Package structure under `com.contentstack.cms`, Java 8 compatibility, Lombok, imports, and code style in this repo. |
 | [testing](testing/SKILL.md) | Adding or fixing tests, Surefire `skipTests` behavior, MockWebServer or live API tests, env/credentials. |

skills/dev-workflow/SKILL.md

@@ -8,14 +8,15 @@ description: Use when branching, building with Maven, CI, or release/publish wor
 ## When to use
 
 - You need the canonical build/test commands or CI expectations.
-- You are opening a PR and need branch rules (`master` vs `staging`).
+- You are opening a PR and need branch rules (`development` → `master`, GitHub Release publishing).
 - You are changing `pom.xml`, plugins, or publishing configuration.
 
 ## Instructions
 
 ### Repository and branches
 
-- Default collaboration flow is documented in [.github/workflows/check-branch.yml](../../.github/workflows/check-branch.yml): PRs targeting `master` from branches other than `staging` may be blocked; prefer the documented Contentstack branching policy for your team.
+- **Flow:** work merges to **`development`**; **release PRs** go **`development` → `master`** (no `staging`). After `master` moves, [.github/workflows/back-merge-pr.yml](../../.github/workflows/back-merge-pr.yml) can open a PR **`master` → `development`** to stay aligned.
+- **Releases:** create a **GitHub Release** (triggers [.github/workflows/maven-publish.yml](../../.github/workflows/maven-publish.yml) on **`release: created`**). PRs that change `src/main` or `pom.xml` are checked by [.github/workflows/check-version-bump.yml](../../.github/workflows/check-version-bump.yml) (version + `changelog.md`).
 
 ### Maven
 
@@ -33,9 +34,3 @@ description: Use when branching, building with Maven, CI, or release/publish wor
 
 - Run tests locally with `-DskipTests=false` before pushing.
 - Update [changelog.md](../../changelog.md) or version metadata when your team’s release process requires it.
-
-## References
-
-- [AGENTS.md](../../AGENTS.md)
-- [testing/SKILL.md](../testing/SKILL.md)
-- [code-review/SKILL.md](../code-review/SKILL.md)