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