From dc74b1efb9bf512a4b3521e4c471ff49fa5f1067 Mon Sep 17 00:00:00 2001 From: autonomic-bot Date: Wed, 17 Jun 2026 03:36:31 +0000 Subject: [PATCH] =?UTF-8?q?docs(recipe-customization):=20make=20previous/?= =?UTF-8?q?=20a=20documented=20last-resort=20=E2=80=94=20prefer=20not=20to?= =?UTF-8?q?=20use?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous/ base-repair mechanism exists and can be used when updating tests if a previous base won't deploy, but it is explicitly a last resort: reach for it only after the dynamic base (last-green -> main-tip) fails to come up, since each previous/ re-introduces the per-version patching treadmill the dynamic base removed. Most recipes (incl. discourse) need none. --- docs/recipe-customization.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/recipe-customization.md b/docs/recipe-customization.md index 1916cf9..edba963 100644 --- a/docs/recipe-customization.md +++ b/docs/recipe-customization.md @@ -241,6 +241,13 @@ in `previous/` (§5.5b). Reference the overlay from `EXTRA_ENV`'s `COMPOSE_FILE` ### 5.5b Previous-version base repair — `tests//previous/` +> **Prefer NOT to use this — it is a last resort.** The mechanism exists so that, when updating a +> recipe's tests, you *can* bring up a previous base that won't deploy as-published. But reach for it +> only after the dynamic base (last-green → main-tip) has genuinely failed to come up. Every `previous/` +> you add re-introduces the per-version patching treadmill the dynamic base was designed to remove, so +> the bar is **"the base will not deploy any other way."** Most recipes — including discourse, the case +> that motivated this — need NONE. When in doubt, don't add one. + Optional. The MINIMAL config to deploy the *previous (last-green) version* when it can't deploy as-published (e.g. an image relocation `bitnami/* → bitnamilegacy/*`, or an era-specific service/env). Applied to the **base deploy ONLY** and stripped before the head redeploy, so the PR