From 4ffe6adf0a029b52b80f36ee48fa68d345b4813d Mon Sep 17 00:00:00 2001
From: Mandel Olaiya <mandeleolaiya15@icloud.com>
Date: Tue, 31 Mar 2026 03:44:44 +0200
Subject: [PATCH] Document devpi release flow and stable fallback

---
 Jenkinsfile                | 28 ++++++++++++++--
 docs/DEVPI_RELEASE_FLOW.md | 68 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+), 2 deletions(-)
 create mode 100644 docs/DEVPI_RELEASE_FLOW.md

diff --git a/Jenkinsfile b/Jenkinsfile
index 5750d7b..e2ed24b 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -35,6 +35,30 @@ pipeline {
         stage('Build') {
             steps {
                 sh '''
+                    STABLE_INDEX_URL=${STABLE_INDEX_URL:-https://pypi.mandelblog.com/mandel/stable/+simple/}
+                    TESTING_INDEX_URL=${TESTING_INDEX_URL:-https://pypi.mandelblog.com/mandel/testing/+simple/}
+                    ROOT_INDEX_URL=${PIP_EXTRA_INDEX_URL:-https://pypi.mandelblog.com/root/pypi/+simple/}
+                    export STABLE_INDEX_URL
+                    if python3 - <<'PY'
+import os
+import sys
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+url = os.environ["STABLE_INDEX_URL"]
+try:
+    req = Request(url, method='HEAD')
+    with urlopen(req, timeout=10) as response:
+        sys.exit(0 if response.status < 400 else 1)
+except HTTPError as exc:
+    sys.exit(0 if exc.code < 400 else 1)
+except URLError:
+    sys.exit(1)
+PY
+                    then
+                        echo "devpi stable index available, but stable-first install is not enabled yet"
+                    else
+                        echo "devpi stable index not available, using testing as production source"
+                    fi
                     if command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then
                         sudo apt-get update -y
                         sudo apt-get install -y python3-venv python3-pip make build-essential libpq-dev \
@@ -51,8 +75,8 @@ pipeline {
                     . .venv/bin/activate
                     pip install coverage
                     pip install --upgrade pip "setuptools==69.5.1" wheel
-                    PIP_INDEX_URL=${PIP_INDEX_URL:-https://pypi.mandelblog.com/mandel/testing/+simple/} \
-                    PIP_EXTRA_INDEX_URL=${PIP_EXTRA_INDEX_URL:-https://pypi.mandelblog.com/root/pypi/+simple/} \
+                    PIP_INDEX_URL="$TESTING_INDEX_URL" \
+                    PIP_EXTRA_INDEX_URL="$ROOT_INDEX_URL" \
                     pip install --no-build-isolation --pre --editable . setuptools wheel --upgrade --upgrade-strategy=eager --use-deprecated=legacy-resolver
                     cp "${JOB_BASE_NAME}/ocyan.json" "${JOB_BASE_NAME}/${JOB_BASE_NAME}.json"
                     pip install ruff vdt.versionplugin.wheel
diff --git a/docs/DEVPI_RELEASE_FLOW.md b/docs/DEVPI_RELEASE_FLOW.md
new file mode 100644
index 0000000..05290f4
--- /dev/null
+++ b/docs/DEVPI_RELEASE_FLOW.md
@@ -0,0 +1,68 @@
+## Devpi Release Flow
+
+### Current state
+
+- `mandel/testing` is the active package source for MandelBlog project builds.
+- `ocyan.plugin.template_engine==0.2.12` is published there and is the current production-safe version.
+- `mandel/stable` is not available yet.
+
+This means production is intentionally running from the testing index for now, to avoid breaking installs while the stable index is not provisioned.
+
+### Index roles
+
+- `mandel/testing`
+  - pre-production and current fallback source
+  - currently also the active production source until stable exists
+- `mandel/stable`
+  - intended production index
+  - not yet provisioned
+
+### Promotion flow
+
+When `mandel/stable` exists, promote existing artifacts without rebuilding:
+
+```bash
+devpi use https://pypi.mandelblog.com/mandel/testing
+devpi login mandel
+devpi push ocyan-plugin-template-engine==0.2.12 mandel/stable
+```
+
+### Admin prerequisite
+
+Promotion requires a devpi admin to create the production index and grant upload or push permissions.
+
+Recommended admin setup:
+
+```bash
+devpi index -c mandel/stable bases=root/pypi volatile=False acl_upload=mandel,Mandel-publish
+```
+
+### Planned stable-first install order
+
+Do not enable this until `mandel/stable` exists:
+
+```bash
+PIP_INDEX_URL=https://pypi.mandelblog.com/mandel/stable/+simple/
+PIP_EXTRA_INDEX_URL=https://pypi.mandelblog.com/mandel/testing/+simple/
+```
+
+### CI behavior
+
+- If the stable index is missing, Jenkins logs:
+  - `devpi stable index not available, using testing as production source`
+- The build does not fail because of the missing stable index.
+- Installs continue from `mandel/testing`.
+
+### Validation checklist
+
+After stable becomes available and promotion is done:
+
+1. confirm both wheel and sdist are visible in the stable simple index
+2. switch MandelStudio to stable-first
+3. run Jenkins build and deploy
+4. verify installed version is still `0.2.12`
+5. recheck editor validation for:
+   - `/contact/`
+   - `/diensten/`
+   - `#demo`
+   - absolute URLs