Skip to content

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 rollback plan is a record a gate reads, not prose a person remembers. Write it in the release's own file, in the three layers a rollback actually uses, and let the release gate refuse a tag without it — because a plan that exists in a document nobody opens at 02:00 is the same as no plan, and a gate that reads it is the only thing that makes it real.

Layer What it restores Why it is separate
the tag the code a version can be re-cut in minutes; a tag alone restores nothing a reader fetched
the deployment the bytes served the previous deployment is the only address a reader can reach without a rebuild
the objects the artefacts — audio, images, a pack these outlive a deployment and are the layer people forget

A measured instance: this book's own repository did not have such a record, so make release-gate TAG=… was written to refuse a tag whose release file does not name all three. The gate is thirty lines and it exists before the first release needs it, which is the only time it is cheap.

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

  1. Define the pack's seven fields. Checkpoint: every field has a source.
  2. Generate the changelog from log and gates. Checkpoint: no hand-written entries.
  3. Wire the pack check into the release gate. Checkpoint: a missing gate result refuses the tag.
  4. Write the rollback decision. Checkpoint: it predates the release.
  5. 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.

  1. Four parts — tag, evidence pack, announcement, rollback plan.
  2. Seven fields, every one generated from a record, and limits is the one reviewers read first.
  3. Generated, not authored — a pack written from memory is a claim, and the changelog follows the same rule.
  4. Trains are a decision, not canon: on-demand until coordination costs more than it saves.
  5. The agent assembles; the human signs — because the pack must be readable cold by someone who did not write it.