Catalog Release Management: Validation, Change Logs, and Rollback
How to ship a named set of catalog changes with a validation result, a change log, a release window, and a rollback path.
- 01 Freeze the scope
- 02 Validate the set
- 03 Write the log
- 04 Prepare rollback
A release is a named set of changes
A catalog release is not the moment someone clicks publish. It is a named set of record changes that have passed the same checks and will become visible together, or not at all. If changes drip out with no name, you cannot say what “yesterday’s catalog” contained, and you cannot put it back.
Give the set an identifier that is not only a timestamp. A timestamp says when a job ran. An identifier says which changes were supposed to be in it. You will need that distinction when a job runs twice.
The set has a scope: which record types, which channels, and which field groups. A scope that says “everything that changed this week” is a scope. A scope that says “the usual stuff” is not. Freeze the scope before validation. A change added after validation is a different release, or the validation has to be repeated.
This stage is the last of the four stages of a catalog change. It does not replace intake or the metadata check. It assumes those happened and asks whether this particular set may go out.
This diagram scrolls sideways on a narrow screen.
Validate the set, not a sample you hope is typical
Validation for release re-checks the rules that already exist. It does not invent new field definitions at the door. Pre-release metadata checks are the metadata part. Duplicate and conflict holds should already have stopped records that are not allowed to ship. A release that includes a record still marked “hold” is a process failure, not a judgment call.
Run the checks on the records in the set. A sample is useful only as a smoke test before the full run. It is not evidence that the records you did not open are fine. If the full run is too large to finish in the window, the set is too large. Split it. Do not skip the remainder.
Record the rule versions used. A release validated against last month’s vocabulary is not validated against today’s. If the vocabulary changed after you froze the scope, either repeat validation or take the vocabulary change out of this release.
The result is a list: records that pass, records removed from the set, and the reason each one was removed. “Fixed during release” without a reason is how unreviewed edits ride along.
Write a change log a later reader can use
The log is the public or internal memory of the set. For each change, or for each group of identical changes, record:
- the release identifier
- the record identifier
- the field group
- what changed, at the level your policy allows you to store
- the rule version
- whether the change shipped
Who is allowed to change the record should already have been applied. The log cites that rule. It does not re-decide it. If the log cannot name the rule, the change is not ready.
Do not fill the log with praise, blame, or a story about a customer. Those additions are not facts the next release needs, and invented customers are not a documentation style. A later incident needs identifiers and actions.
If a class of change is too sensitive to spell out in a widely read log, say that the value changed and point to the restricted record. An empty log line is worse than a restricted one, because it looks like the release had no content.
Choose a window, then keep a way back
A release window is the time during which this set is allowed to become visible. It is a planning constraint. It is not a quality result. A quiet hour does not make a bad record good. It only limits how many people see a failure if rollback is needed.
Rollback is the decision to return to the previous named release, or to withdraw this set. Prepare it before you start. Preparation means you know:
- which previous release identifier is the return point
- which copies, including caches and indexes, must follow
- who is allowed to declare the rollback
- how you will tell the change log that this release was withdrawn
If you cannot name the return point, you do not have rollback. You have a hope that someone can edit the records back by hand. That may be the only option for a catalog that has never named a release. It should not stay the option after this one.
A partial rollback, withdrawing some records and leaving others, is a new release with a smaller scope. Do not describe it as “undoing the bad ones” without giving that smaller set its own identifier and log.
This table scrolls sideways on a narrow screen.
| Artifact | Question it answers | Not the same as |
|---|---|---|
| Release identifier | Which set is this? | A job timestamp |
| Scope | Which records and fields were allowed in? | A folder of exports |
| Validation result | Which records passed the current rules? | A spot check of a few rows |
| Change log | What shipped, under which rule? | A chat transcript |
| Rollback note | What do we return to, and who may say so? | A backup that nobody has tried to read |
Watch the release, and write incidents as facts
After the set is visible, watch the signals you actually have: error responses from the catalog service, a count of records that failed to publish, a check that the release identifier in production is the one you intended. Do not invent a dashboard you do not run. Name the signals in the release note so the next release watches the same ones.
An incident is a later discovery that the shipped set was wrong: a rule missed, a copy that did not refresh, a rollback that itself failed. The incident note should say what was observed, which release identifier was live, and what was done. It should not estimate lost revenue or name a customer. If you roll back, the change log should show the withdrawal.
W3C Best Practice 27, about preserving identifiers when data is removed from the web, matters if a rollback or a withdrawal removes a public URL. The recommendation says to preserve the identifier and provide information about the archived resource. A rollback that leaves a public identifier as a bare failure, with no pointer to the previous record or an explanation, throws away the only handle people had. That is a separate question from whether the previous release was the right return point.
What this method does not promise
It does not promise zero defects. It promises that a defect has a release identifier to attach to, and a previous identifier to return to. It does not set a maximum number of changes per window. A team that needs a limit should write a local limit and own it. This page will not invent one.
It also does not treat editorial corrections on this website as catalog rollbacks. A correction to a guide is recorded on the corrections page. A correction to a catalog record is a catalog change and belongs in the catalog log.
When a release should stop
When is a window not enough reason to ship?
When validation has not finished, or when the rollback return point is unnamed. A quiet hour does not replace either artifact.
When needed: Before the set becomes visible.
When can you add a record after validation?
You can add it to a new set and validate that set. Adding it to a set that already passed makes the previous result incomplete.
When needed: Any late change, including a one-line fix.
When is a rollback complete?
When the declared return point is the release identifier in production, the copies that must follow have followed, and the log says this set was withdrawn.
When needed: After the decision to roll back, before the incident note is closed.