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

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

@@ -0,0 +1,56 @@
+# Opens a PR from main → development after changes land on main (back-merge).
+
+name: Back-merge main to development
+
+on:
+  push:
+    branches: [main]
+  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 main
+
+          MAIN_SHA=$(git rev-parse origin/main)
+          DEV_SHA=$(git rev-parse origin/development)
+
+          if [ "$MAIN_SHA" = "$DEV_SHA" ]; then
+            echo "main and development are at the same commit; nothing to back-merge."
+            exit 0
+          fi
+
+          EXISTING=$(gh pr list --repo "${{ github.repository }}" \
+            --base development \
+            --head main \
+            --state open \
+            --json number \
+            --jq 'length')
+
+          if [ "$EXISTING" -gt 0 ]; then
+            echo "An open PR from main to development already exists; skipping."
+            exit 0
+          fi
+
+          gh pr create --repo "${{ github.repository }}" \
+            --base development \
+            --head main \
+            --title "chore: back-merge main into development" \
+            --body "Automated back-merge after changes landed on \`main\`. Review and merge to keep \`development\` in sync."
+
+          echo "Created back-merge PR main → development."

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

@@ -0,0 +1,110 @@
+# Release-affecting changes under contentstack_management/ or setup.py require
+# __version__ + CHANGELOG.md updates aligned with the latest tag.
+
+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" == contentstack_management/* ]] || [[ "$f" == "setup.py" ]]; then
+              CODE_CHANGED=true
+              break
+            fi
+          done <<< "$FILES"
+
+          INIT_CHANGED=false
+          CHANGELOG_CHANGED=false
+          echo "$FILES" | grep -qx 'contentstack_management/__init__.py' && INIT_CHANGED=true
+          echo "$FILES" | grep -qx 'CHANGELOG.md' && CHANGELOG_CHANGED=true
+
+          VERSION_FILES_OK=false
+          if [ "$INIT_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 contentstack_management or setup.py changes. Skipping version-bump check."
+          exit 0
+
+      - name: Fail when version files were not both updated
+        if: steps.detect.outputs.code_changed == 'true' && steps.detect.outputs.version_files_ok != 'true'
+        run: |
+          echo "::error::Bump __version__ in contentstack_management/__init__.py 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
+          PKG_VERSION=$(python3 <<'PY'
+          import re
+          text = open("contentstack_management/__init__.py").read()
+          m = re.search(r"^__version__\s*=\s*['\"]([^'\"]+)['\"]", text, re.MULTILINE)
+          if not m:
+              raise SystemExit("Could not read __version__ from contentstack_management/__init__.py")
+          print(m.group(1).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."
+            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" != "$PKG_VERSION" ]; then
+              echo "::error::CHANGELOG top version ($CHANGELOG_HEAD) does not match __version__ ($PKG_VERSION)."
+              exit 1
+            fi
+            exit 0
+          fi
+
+          LATEST_VERSION="${LATEST_TAG#v}"
+          LATEST_VERSION="${LATEST_VERSION%%-*}"
+          if [ "$(printf '%s\n' "$LATEST_VERSION" "$PKG_VERSION" | sort -V | tail -1)" != "$PKG_VERSION" ]; then
+            echo "::error::__version__ ($PKG_VERSION) must be greater than latest tag ($LATEST_TAG)."
+            exit 1
+          fi
+          if [ "$PKG_VERSION" = "$LATEST_VERSION" ]; then
+            echo "::error::__version__ ($PKG_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" != "$PKG_VERSION" ]; then
+            echo "::error::CHANGELOG top version ($CHANGELOG_HEAD) does not match __version__ ($PKG_VERSION)."
+            exit 1
+          fi
+          echo "Version bump check passed: __version__ and CHANGELOG at $PKG_VERSION (latest tag: $LATEST_TAG)."

requirements.txt

@@ -1,4 +1,4 @@
-python-dotenv>=1.0.0,<2.0.0
+python-dotenv>=1.2.2
 # <82: pkg_resources (used by coverage-badge and similar tools) was removed in setuptools 82+
 setuptools>=80.0.0,<82.0.0
 requests>=2.33.0,<3.0.0

skills/dev-workflow/SKILL.md

@@ -10,6 +10,11 @@ description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard
 - Setting up locally, opening a PR, or matching CI expectations.
 - Answering “how do we run tests?” or “what runs in CI?”
 
+## Branches & releases
+
+- **Flow:** merge work to **`development`**; **release PRs** are **`development` → `main`**. After **`main`** moves, [`.github/workflows/back-merge-pr.yml`](../../.github/workflows/back-merge-pr.yml) can open **`main` → `development`** to resync.
+- **PyPI:** publish a **GitHub Release** (`release: published`) to run [`.github/workflows/release.yml`](../../.github/workflows/release.yml). PRs that touch **`contentstack_management/`** or **`setup.py`** must bump **`__version__`** and **`CHANGELOG.md`** per [`.github/workflows/check-version-bump.yml`](../../.github/workflows/check-version-bump.yml).
+
 ## Before a PR
 
 1. **Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed.