Document devpi release flow and stable fallback

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