DailyRNG
Login
Master

A release plan for a containerized product

A release plan is one page that names what ships, what must not change, what data moves, and what has to be true before the publish step runs. Everything else in the container workflow is a detail of that page. If the page is wrong, the details are correct and the release is still wrong.

What you will see

Both files mention the same gate. If the script has a step the plan does not name, the plan is out of date and the release is undescribed.

About 2 min of reading

Try It

Write a plan page and derive the gate from it

1

Create the plan

printf '# v1.4.2\n\nShips: app:v1.4.2\nFrozen: run(), parse(), CLI flag --out\nMoves: migrations 001-004\nGate: ./release-gate.sh\n' | tee plans/v1.4.2.md

Before you run it, say out loud what it will print. Then open the answer.

What it prints
A page with all four sections filled. Empty sections say 'none'.
2

Turn Frozen into a test

grep -o 'Frozen: .*' plans/v1.4.2.md | cut -d' ' -f2- | tr ',' '\n' | sed 's/^ *//' | tee frozen.txt

Before you run it, say out loud what it will print. Then open the answer.

What it prints
One name per line, each of which a test must assert is present and unchanged.
3

Turn Moves into a command

grep -o 'Moves: .*' plans/v1.4.2.md | cut -d' ' -f2-

Before you run it, say out loud what it will print. Then open the answer.

What it prints
The migration range. The gate runs exactly this range and nothing else.
4

Check the gate matches the plan

grep -c 'release-gate.sh' plans/v1.4.2.md release-gate.sh

Before you run it, say out loud what it will print. Then open the answer.

What it prints
Both files mention the same gate. If the script has a step the plan does not name, the plan is out of date and the release is undescribed.
If you cannot fill the Frozen section, you have not identified what a consumer depends on. Stop and ask them; do not ship an empty Frozen section.

Data Flow

Plan to gate to publish
1 Write the plan page before building
↓
2 Build the artifacts named in Ships
↓
3 Run the frozen-interface tests from Frozen
↓
4 Run the gate command; publish only on zero
Why this works
The frozen section is the load-bearing one

Everything a consumer depends on goes in Frozen, and a test asserts each entry is unchanged. That test is the release; the changelog is a description of it.

Where the plan lives

In the repo, one file per release, named by version. A release that has no plan file is a release nobody can explain later, which is the cheapest kind of release to regret.

Examples

Four sections, no more

Ships: the tagged artifacts. Frozen: the interfaces that must not change. Moves: the data migrations. Gate: the command that must exit zero. If a section is empty, say so with 'none' rather than leaving it out.

The plan is written before the build

Writing it after the build lets you describe what you did instead of what you intended. The plan is the input to the build, and the build is checked against the plan.

One owner, one review

The plan is reviewed by the person who consumes the artifact, not the person who built it. If nobody outside the build can read the plan and say 'yes, that is what I need', the plan is not a plan.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Versioning inside a monorepo
Previous Lesson
Versioning inside a monorepo
Next Lesson
Debugging a container that will not start
Debugging a container that will not start →