Chapter 24: Release Management and the Evidence Pack¶
A Reviewer Should Not Need to Ask You Anything¶
Versions become releases when a reviewer can decide without asking you anything; this chapter builds the pack that lets them.
1. What a Release Is¶
The three structures produce work; a release is where that work becomes a promise to someone else. A release is a tag, an evidence pack, an announcement, and a rollback plan — and a deploy is only the mechanism that carries it.
That distinction is the chapter's spine: the deploy can be automated completely, and the release still requires a decision, because the release is what a consumer trusts.
🎯 What You'll Learn¶
- The four parts of a release, and what each proves
- Why the evidence pack is generated, never authored
- What an agent prepares, and what a human signs
The Four Parts¶
| Part | Proves | Who |
|---|---|---|
| the tag | what exactly shipped | the human who signs |
| the evidence pack | what was verified, and what was not | generated from the gates |
| the announcement | who needs to know, and what changes for them | the human |
| the rollback plan | what happens if it goes wrong | written before the release |
A release without an evidence pack is a hope with a version number. A release without a rollback plan is a decision made under pressure later.
The Evidence Pack¶
Per release, seven fields:
# evidence pack — one file per release
release: <tag>
gates: [{ id: <gate>, result: pass|fail|blocked }]
verify: <what ran against the artefact, and the result>
drills: <drill freshness at release time>
provenance: <who built it, from which commit>
limits: [<known limitations, stated>]
rollback: <the decision, written before the release>
Every field is a fact someone recorded, not a narrative someone wrote. limits is the one teams omit, and it is the one a reviewer reads first: a known limitation stated is a risk accepted; the same limitation discovered later is a surprise.
✅ What to Check¶
- Does your last release have all seven fields?
- Was the rollback decision written before the release, or during the incident?
2. Generated, Not Authored¶
The pack is assembled from the log and the gates, never written from recollection. A pack written by hand is a claim about a run; a pack generated from records is evidence of it.
| Source | Field it fills |
|---|---|
| the gate records | gates |
| the verification run | verify |
| the drill records | drills |
| the pipeline | provenance |
| the release decision | rollback |
The changelog follows the same rule. Written from the log and the gates, it says what changed and what was verified — not what someone remembers intending.
✅ What to Check¶
- If the pack were regenerated tomorrow, would it match the release?
- Is any field of the pack written by hand? Which one, and why?
3. Release Trains and Cadence¶
A release train — a scheduled cadence over many services — is a legitimate choice, and it has a real cost: coordination. There is no normative definition of one outside a scaled framework, so this is a decision, not canon.
| Choice | Suits | Costs |
|---|---|---|
| on-demand | few services, strong gates | every release is a decision |
| release train | many services, coordinated changes | waiting, and a batch risk |
Default: on-demand, until coordination costs more than the train saves. A team that adopts a train before it has the coordination problem has added a schedule to its gates for no benefit.
staging → production derived from the trigger, never from a filename or a human's memory. A deploy that depends on remembering which file to edit is a deploy that will be edited wrongly.
✅ What to Check¶
- If you run a train, what does the train buy you — and can you name the cost?
- Is your environment decided by a trigger, or by a person's memory?
4. The AI Delta¶
An agent can assemble a pack that is complete in form and false in substance: it optimises for the fields being filled, not for the gates having passed.
So the pack must be generated from evidence — and the human signs what they did not write, which is exactly why the pack has to be readable cold.
💰 Cost Check: an incomplete pack costs a reviewer's afternoon and a release they cannot defend. A pack written from memory costs the audit that contradicts it. A release train adopted too early costs waiting on every change. The generated pack costs the pipeline work once, and pays on every release after.
flowchart LR
G["gate records"] --> P["evidence pack<br/>generated"]
V["verification"] --> P
D["drill records"] --> P
P --> H{"human reads and signs"}
H --> T["the tag"]
T --> A["an auditable release"]
What this shows: every field has a source, and the human's signature is the only hand-written part.
The Delegation Line¶
The agent assembles the pack, the changelog and the version bump. The human decides the release and signs the tag. The system refuses a tag whose pack names a gate that did not pass.
5. Build the Delivery¶
Deliverables¶
| Artefact | Shape | Where it lives |
|---|---|---|
| release checklist | the steps with their evidence | the Playbook |
| evidence pack | seven fields, generated | releases/<tag>/evidence.yaml |
| changelog | generated from log and gates | beside the pack |
| rollback decision | written before the release | the pack |
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| cadence | on-demand | a train, once coordination costs more than it saves |
| who signs | a human signs the tag; an agent assembles | an unsigned release nobody owns |
| the pack | generated | a hand-written claim |
| the rollback decision | before the release | improvised during the incident |
✅ Gates¶
- A release whose pack is incomplete is refused at the tag.
- A deploy from a commit that is not the tagged one is refused.
- A pack that names a failed gate cannot be signed.
Runbook¶
- Define the pack's seven fields. Checkpoint: every field has a source.
- Generate the changelog from log and gates. Checkpoint: no hand-written entries.
- Wire the pack check into the release gate. Checkpoint: a missing gate result refuses the tag.
- Write the rollback decision. Checkpoint: it predates the release.
- Ship one release and read the pack cold. Checkpoint: a reviewer needs no conversation.
🎯 Proof¶
- A release a reviewer can audit without asking you anything.
- A pack that fails when a gate result is missing.
- A rollback decision that existed before the release.
6. 🔑 Chapter Summary¶
A release is a decision with evidence; the deploy is only its mechanism.
- Four parts — tag, evidence pack, announcement, rollback plan.
- Seven fields, every one generated from a record, and
limitsis the one reviewers read first. - Generated, not authored — a pack written from memory is a claim, and the changelog follows the same rule.
- Trains are a decision, not canon: on-demand until coordination costs more than it saves.
- The agent assembles; the human signs — because the pack must be readable cold by someone who did not write it.