Rebase, and fix held overlays
Lesson 16 of 25 6 min read
Change how an overlay follows its base, and bring a held overlay back onto the current version.
Overlays live alongside a base that keeps changing. Sometimes you need to pin one, unpin it, or rescue one that a publish parked. All three use Rebase. In this lesson you will rebase an overlay and work through fixing a held one.
Rebase an overlay
Rebase changes how an overlay follows its base.
- On the overlay, select Rebase.
- Select Follow whatever the base publishes, or Hold it on one version and choose the Base version.
- Select Rebase.
If the overlay does not fit the version you chose, nothing changes, and Prism tells you: That does not compose, so nothing was changed. "Compose" means the overlay's changes can be applied to that base version, for example because every node id it targets exists there.
A rebase either works completely or changes nothing, so it is safe to try.
| You want to | Choose |
|---|---|
| Unpin a pinned overlay so it gets base improvements again | Follow whatever the base publishes |
| Freeze an overlay during a busy period | Hold it on one version, and the current base version |
| Move a pinned overlay to a newer version, but still pinned | Hold it on one version, and the newer version |
Held overlays
An overlay is Held when a new version of its base broke it, and the base was published anyway with Publish anyway and park them. The organisation's overview shows a warning.
A held overlay still runs, on the old base version. That is the point: the customer keeps working. But they miss everything the newer base version changed, so a held overlay needs fixing.
Fix a held overlay
- Open the held overlay and find out what broke. Compare the old and new base versions in Versions to see what changed, for example a node that was renamed or removed.
- Edit the overlay so that it fits the new base, for example by targeting the new node id.
- Publish the overlay.
- Select Rebase, then Follow whatever the base publishes.
- Check the overview: the held warning should be gone. Use End result to confirm the result.
What the developer notes add
The developer documentation says the next publish of the base that moves followers (Move everyone who is following) also re-checks held overlays, and moves any that now fit. It also describes Supply Lens retiring an overlay automatically on release when the shipped base has absorbed exactly what the overlay did. Do not rely on either: fix held overlays yourself, and check with the platform team if an overlay seems to have disappeared after a release.
Rescuing Hilltop's express overlay
A release brings Acme orders v2, which renames order.priority to order.serviceLevel. Hilltop's Acme orders: express overlay targets order.priority, so the publish holds it on v1. Hilltop's overview shows the held warning.
You compare v1 and v2 of the base in Versions and spot the rename. Your developer changes the overlay's target to order.serviceLevel. You publish the overlay, then Rebase with Follow whatever the base publishes. End result now shows Root: Acme orders v2 → Overlay 1: Acme orders: express v2, with a solid chip on order.serviceLevel. The warning has gone.
Recap
- Rebase switches an overlay between following the base and holding it on one version.
- A rebase that does not fit changes nothing: That does not compose, so nothing was changed.
- Held overlays still run, on the old base version, but miss newer base changes.
- To fix one: edit it to fit the new base, publish it, then rebase to follow the base.
- Watch the overview for the held warning.
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.