# Release Readiness & Rollback

Puts a change into an environment with the checks, the watch, the stop signals and the way back written down before it goes.

## Deliverable

One Markdown document, `release-runbook.md`, in the structure set out under **Output** below. It is executed at release time and kept with the record of what happened.

## Required inputs

- **The change set going out** — what is included, at which revision, and what it changes for the people using the system.
- **The target environment** — where it goes, what already runs there, and who is responsible for it.

If either is absent, stop and report it. A runbook written without knowing what is already running cannot say what the release changes.

## Optional inputs

- The deployment mechanism, and whether it can hold two versions at once
- Monitoring, alerting and the signals already watched in that environment
- Data changes in the set: schema migrations, backfills, format changes
- The release window, who is available during it, and who must approve
- Dependent systems and the people who own them
- The record of previous releases to this environment, and how they went

Where an optional input is absent, the runbook names it as a gap in the go / no-go list and does not assume the capability exists.

## Execution

**1 — Inventory what is going out.** Every change in the set, with its revision, and what each one changes for the people using the system. Anything in the set that nobody expected to be released is stopped here rather than discovered afterwards.

**2 — Write the pre-release checks with their pass conditions.** Each check states what is run, who runs it, and what result allows the release to proceed. A check with no pass condition is a ritual: it will be performed and it will decide nothing.

**3 — Order the deployment steps.** Each step in sequence, with what it does, who does it, and how to confirm it worked before the next one starts. Where dependent systems must move in a particular order, that order is part of the sequence and names the owner of each.

**4 — Define the watch.** What is observed after the release, where it is observed, and for how long — stated as a period someone commits to, not as an indefinite watch. Include the signals that were normal before the release, so that a change in them is visible.

**5 — Set the stop signals.** The specific observations that end the release and trigger the rollback, decided before the release rather than argued about during it. Each one names who can call it.

**6 — Write the rollback as its own procedure.** Its steps, who runs them, how to confirm the system is back, and what it costs in time. A rollback that has not been written down is a plan to improvise under pressure.

**7 — Name what cannot be rolled back.** Data changes, irreversible migrations, messages already sent, external systems already told. These set the real point of no return, and they are listed explicitly with the step after which they apply.

## Output

`release-runbook.md`, in this order:

- **1. Change set** — what is going out, at which revision, and what changes for the people using the system
- **2. Target environment** — where, what runs there now, and who owns it
- **3. Pre-release checks** — per check: what is run, by whom, and the result that allows the release
- **4. Deployment steps** — ordered; per step: the action, the owner, and the confirmation before the next one
- **5. Watch** — what is observed, where, for how long, and what normal looked like before
- **6. Stop signals** — the observations that end the release, and who may call each
- **7. Rollback** — the steps, the owner, the confirmation, and the time it costs
- **8. Not reversible** — the changes that cannot be undone, and the step after which they apply
- **9. Go / no-go** — one line per condition, each answered yes, no or `unknown`
- **10. Gaps** — what could not be established, and who can establish it

## Validation

The runbook is ready when all of these hold:

- Every item in section 1 names its revision and what it changes for the people using the system
- Every check in section 3 states a pass condition, not only an action
- Every deployment step names an owner and a confirmation
- Section 5 states a period and what normal looked like before the release
- Section 7 gives a rollback whose steps are as specific as the deployment steps, with its cost in time
- Section 8 is either populated or states explicitly that nothing in the set is irreversible

Fail the run if the rollback is less detailed than the deployment, or if section 9 carries a condition answered `unknown` and the list is still presented as a go.

## Failure handling

- **No rollback is possible** — say so in section 7, name what makes it impossible, and require the go / no-go to be approved on that basis by the owner named in section 2.
- **An unrehearsed data change in the set** — answer that condition `no` in section 9. A data change that has not been rehearsed against a copy of the target data is the one step of a release that cannot be taken back.
- **No monitoring in the target environment** — state in section 5 that the release is unobserved, describe the manual checks that stand in for it, and record the gap in section 10.
- **Unknown conditions at release time** — list every one of them in section 9 as `unknown` and present the list as a no-go. A go / no-go list with unknowns on it is not a go.
- **The window closes mid-release** — stop at the last step that carried a confirmation, roll back to it if the current step cannot complete, and record where it stopped. A release left half-applied is worse than one not started.