docs(recipe-customization): make previous/ a documented last-resort — prefer not to use
All checks were successful
continuous-integration/drone/push Build is passing

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.
This commit is contained in:
2026-06-17 03:36:31 +00:00
parent eff8b1a93f
commit dc74b1efb9

View File

@ -241,6 +241,13 @@ in `previous/` (§5.5b). Reference the overlay from `EXTRA_ENV`'s `COMPOSE_FILE`
### 5.5b Previous-version base repair — `tests/<recipe>/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