Master

Shipping the performance change safely

A performance change is a shipped change like any other: it needs a token, a rollout, and a rollback. The token is what makes the new asset reachable to new visitors and the old one intact for cached ones. The rollback is what makes a bad change reversible in one step.

What you will see

The gate passes on the old token. If it does not, the rollback is broken and the ship should not have happened.

About 1 min of reading

Try It

Ship one performance change with a rollback

1

Token the new asset

grep -nE 'main\.css\?v=' views/partials/head.ejs

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

What it prints
The link line with the new token. Only one line should carry it.
2

Confirm the old variant still serves

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/public/css/main.css?v=20261009

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

What it prints
200. The previous token stays reachable so cached visitors are not broken.
3

Run the gate after the ship

./perf-gate.sh; echo "exit=$?"

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

What it prints
exit=0 on the shipped page, not on a local file. The gate must hit the served URL.
4

Practice the rollback

revert the token in head.ejs to the previous value, reload, run the gate

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

What it prints
The gate passes on the old token. If it does not, the rollback is broken and the ship should not have happened.
Never delete the previous tokened file from disk. Cached visitors request it, and a missing file is a broken page for them.

Data Flow

Change to a reversible ship
1 Land the change in the source
↓
2 Serve the new tokened asset
↓
3 Keep the previous tokened asset
↓
4 Run the gate and record the number
Why this works
The order of a performance ship

Land the change, token the asset, keep the previous variant, run the gate, record the number. Five steps, and each one is checkable.

What makes it reversible

The previous tokened file is still served and the HTML edit is one line. Reversibility is a property of the files, not of the person.

Examples

Token the changed asset

The new CSS or JS gets a new token in the URL. Nothing in the HTML points at the old token, so a fresh visitor never asks for a stale file.

Keep the old variant on disk

The previous tokened file stays served for the window. Removing it turns a cached visitor into a 400-range response.

Roll back by pointing back

Rolling back is editing the HTML back to the old token, not deleting the new one. The new file can stay unused on disk while you confirm the old one works.

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.

← Guarding against a regression after the fix
Previous Lesson
Guarding against a regression after the fix